lib/Catalyst/Manual/Tutorial/Appendices.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::Appendices - Catalyst Tutorial - Part 9: Appendices
   4
   5
   6 =head1 OVERVIEW
   7
   8 This is B<Part 9 of 9> of the Catalyst tutorial.
   9
  10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
  11
  12 =over 4
  13
  14 =item 1
  15
  16 L<Introduction|Catalyst::Manual::Tutorial::Intro>
  17
  18 =item 2
  19
  20 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  21
  22 =item 3
  23
  24 L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
  25
  26 =item 4
  27
  28 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  29
  30 =item 5
  31
  32 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  33
  34 =item 6
  35
  36 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
  37
  38 =item 7
  39
  40 L<Testing|Catalyst::Manual::Tutorial::Testing>
  41
  42 =item 8
  43
  44 L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  45
  46 =item 9
  47
  48 B<Appendices>
  49
  50 =back
  51
  52 =head1 DESCRIPTION
  53
  54 This part of the tutorial provides supporting information relevant to
  55 the Catalyst tutorial.
  56
  57 =head1 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
  58
  59 You may notice that Pod indents example code with four spaces.  This
  60 section provides some quick advice to "un-indent" this text in common
  61 editors.
  62
  63 =head2 "Un-indenting" with Vi/Vim
  64
  65 When cutting and pasting multi-line text from Pod-based documents, the
  66 following vi/vim regexs can be helpful to "un-indent" the inserted text
  67 (do NOT type the quotes, they are only included to show spaces in the
  68 regex patterns).  I<Note that all 3 of the regexs end in 4 spaces>:
  69
  70 =over 4
  71
  72 =item *
  73
  74 ":0,$s/^    "
  75
  76 Removes four leading spaces from the entire file (from the first line,
  77 C<0>, to the last line, C<$>).
  78
  79 =item *
  80
  81 "%$s/^    "
  82
  83 A shortcut for the previous item (C<%> specifies the entire file; so
  84 this removes four leading spaces from every line).
  85
  86 =item *
  87
  88 ":.,$s/^    "
  89
  90 Removes the first four spaces from the line the cursor is on at the time
  91 the regex command is executed (".") to the last line of the file.
  92
  93 =item *
  94
  95 ":.,44s/^    "
  96
  97 Removes four leading space from the current line through line 44
  98 (obviously adjust the C<44> to the appropriate value in your example).
  99
 100 =back
 101
 102 =head2 "Un-indenting" with Emacs
 103
 104 B<TODO>
 105
 106 =head1 APPENDIX 2: USING MYSQL AND POSTGRESQL
 107
 108 The main database used in this tutorial is the very simple yet powerful
 109 SQLite.  This section provides information that can be used to "convert"
 110 the tutorial to use MySQL and PostgreSQL.  However, note that part of
 111 the beauty of the MVC architecture is that very little database-specific
 112 code is spread throughout the system (at least when MVC is "done
 113 right").  Consequently, converting from one database to another is
 114 relatively painless with most Catalyst applications.  In general, you
 115 just need to adapt the schema definition C<.sql> file you use to
 116 initialize your database and adjust a few configuration parameters.
 117
 118 Also note that the purpose of the data definition statements for this
 119 section are not designed to take maximum advantage of the various
 120 features in each database for issues such as referential integrity and
 121 field types/constraints.
 122
 123 =head2 MySQL
 124
 125 Use the following steps to adapt the tutorial to MySQL.  Thanks to Jim
 126 Howard for the help.
 127
 128 =over 4
 129
 130 =item *
 131
 132 Part 2: Catalyst Basics
 133
 134 =over 4
 135
 136 =item *
 137
 138 Install the required software:
 139
 140 =over 4
 141
 142 =item *
 143
 144 The MySQL database server and client utility.
 145
 146 =item *
 147
 148 The Perl C<DBD::MySQL> module
 149
 150 =back
 151
 152 For CentOS users (see
 153 L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>),
 154 you can use the following commands to install the software and start the MySQL
 155 daemon:
 156
 157     yum -y install mysql mysql-server
 158     service mysqld start
 159
 160 =item *
 161
 162 Create the database and set the permissions:
 163
 164     $ mysql
 165     Welcome to the MySQL monitor.  Commands end with ; or \g.
 166     Your MySQL connection id is 2 to server version: 4.1.20
 167
 168     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 169
 170     mysql> create database myapp;
 171     Query OK, 1 row affected (0.01 sec)
 172
 173     mysql> grant all on myapp.* to tutorial@'localhost';
 174     Query OK, 0 rows affected (0.00 sec)
 175
 176     mysql> flush privileges;
 177     Query OK, 0 rows affected (0.00 sec)
 178
 179     mysql> quit
 180     Bye
 181
 182 =item *
 183
 184 Create the C<.sql> file and load the data:
 185
 186 =over 4
 187
 188 =item *
 189
 190 Open the C<myapp01_mysql.sql> in your editor and enter:
 191
 192     --
 193     -- Create a very simple database to hold book and author information
 194     --
 195     DROP TABLE IF EXISTS books;
 196     DROP TABLE IF EXISTS book_authors;
 197     DROP TABLE IF EXISTS authors;
 198     CREATE TABLE books (
 199            id          INT(11) PRIMARY KEY,
 200            title       TEXT ,
 201            rating      INT(11)
 202     );
 203     -- 'book_authors' is a many-to-many join table between books & authors
 204     CREATE TABLE book_authors (
 205            book_id     INT(11),
 206            author_id   INT(11),
 207            PRIMARY KEY (book_id, author_id)
 208     );
 209     CREATE TABLE authors (
 210            id          INT(11) PRIMARY KEY,
 211            first_name  TEXT,
 212            last_name   TEXT
 213     );
 214     ---
 215     --- Load some sample data
 216     ---
 217     INSERT INTO books VALUES (1, 'CCSP SNRS Exam Certification Guide', 5);
 218     INSERT INTO books VALUES (2, 'TCP/IP Illustrated, Volume 1', 5);
 219     INSERT INTO books VALUES (3, 'Internetworking with TCP/IP Vol.1', 4);
 220     INSERT INTO books VALUES (4, 'Perl Cookbook', 5);
 221     INSERT INTO books VALUES (5, 'Designing with Web Standards', 5);
 222     INSERT INTO authors VALUES (1, 'Greg', 'Bastien');
 223     INSERT INTO authors VALUES (2, 'Sara', 'Nasseh');
 224     INSERT INTO authors VALUES (3, 'Christian', 'Degu');
 225     INSERT INTO authors VALUES (4, 'Richard', 'Stevens');
 226     INSERT INTO authors VALUES (5, 'Douglas', 'Comer');
 227     INSERT INTO authors VALUES (6, 'Tom', 'Christiansen');
 228     INSERT INTO authors VALUES (7, ' Nathan', 'Torkington');
 229     INSERT INTO authors VALUES (8, 'Jeffrey', 'Zeldman');
 230     INSERT INTO book_authors VALUES (1, 1);
 231     INSERT INTO book_authors VALUES (1, 2);
 232     INSERT INTO book_authors VALUES (1, 3);
 233     INSERT INTO book_authors VALUES (2, 4);
 234     INSERT INTO book_authors VALUES (3, 5);
 235     INSERT INTO book_authors VALUES (4, 6);
 236     INSERT INTO book_authors VALUES (4, 7);
 237     INSERT INTO book_authors VALUES (5, 8);
 238
 239 =item *
 240
 241 Load the data:
 242
 243     mysql -ututorial myapp < myapp01_mysql.sql
 244
 245 =item *
 246
 247 Make sure the data loaded correctly:
 248
 249     $ mysql -ututorial myapp
 250     Reading table information for completion of table and column names
 251     You can turn off this feature to get a quicker startup with -A
 252
 253     Welcome to the MySQL monitor.  Commands end with ; or \g.
 254     Your MySQL connection id is 4 to server version: 4.1.20
 255
 256     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 257
 258     mysql> show tables;
 259     +-----------------+
 260     | Tables_in_myapp |
 261     +-----------------+
 262     | authors         |
 263     | book_authors    |
 264     | books           |
 265     +-----------------+
 266     3 rows in set (0.00 sec)
 267
 268     mysql> select * from books;
 269     +----+------------------------------------+--------+
 270     | id | title                              | rating |
 271     +----+------------------------------------+--------+
 272     |  1 | CCSP SNRS Exam Certification Guide |      5 |
 273     |  2 | TCP/IP Illustrated, Volume 1       |      5 |
 274     |  3 | Internetworking with TCP/IP Vol.1  |      4 |
 275     |  4 | Perl Cookbook                      |      5 |
 276     |  5 | Designing with Web Standards       |      5 |
 277     +----+------------------------------------+--------+
 278     5 rows in set (0.00 sec)
 279
 280     mysql>
 281
 282 =back
 283
 284 =item *
 285
 286 Update the model:
 287
 288 =over 4
 289
 290 =item *
 291
 292 Delete the existing model:
 293
 294     rm lib/MyApp/Model/MyAppDB.pm
 295
 296 =item *
 297
 298 Regenerate the model using the Catalyst "_create.pl" script:
 299
 300     script/myapp_create.pl model MyAppDB DBIC::Schema MyAppDB dbi:mysql:myapp 'tutorial' '' '{ AutoCommit => 1 }'
 301
 302 =back
 303
 304 =back
 305
 306 =item *
 307
 308 Part 4: Authentication
 309
 310 =over 4
 311
 312 =item *
 313
 314 Create the C<.sql> file for the user/roles data:
 315
 316 Open C<myapp02_mysql.sql> in your editor and enter:
 317
 318     --
 319     -- Add users and roles tables, along with a many-to-many join table
 320     --
 321     CREATE TABLE users (
 322             id            INT(11) PRIMARY KEY,
 323             username      TEXT,
 324             password      TEXT,
 325             email_address TEXT,
 326             first_name    TEXT,
 327             last_name     TEXT,
 328             active        INT(11)
 329     );
 330     CREATE TABLE roles (
 331             id   INTEGER PRIMARY KEY,
 332             role TEXT
 333     );
 334     CREATE TABLE user_roles (
 335             user_id INT(11),
 336             role_id INT(11),
 337             PRIMARY KEY (user_id, role_id)
 338     );
 339     --
 340     -- Load up some initial test data
 341     --
 342     INSERT INTO users VALUES (1, 'test01', 'mypass', 't01@na.com', 'Joe',  'Blow', 1);
 343     INSERT INTO users VALUES (2, 'test02', 'mypass', 't02@na.com', 'Jane', 'Doe',  1);
 344     INSERT INTO users VALUES (3, 'test03', 'mypass', 't03@na.com', 'No',   'Go',   0);
 345     INSERT INTO roles VALUES (1, 'user');
 346     INSERT INTO roles VALUES (2, 'admin');
 347     INSERT INTO user_roles VALUES (1, 1);
 348     INSERT INTO user_roles VALUES (1, 2);
 349     INSERT INTO user_roles VALUES (2, 1);
 350     INSERT INTO user_roles VALUES (3, 1);
 351
 352 =item *
 353
 354 Load the user/roles data:
 355
 356     mysql -ututorial myapp < myapp02_mysql.sql
 357
 358 =item *
 359
 360 Create the C<.sql> file for the hashed password data:
 361
 362 Open C<myapp03_mysql.sql> in your editor and enter:
 363
 364     --
 365     -- Convert passwords to SHA-1 hashes
 366     --
 367     UPDATE users SET password = 'e727d1464ae12436e899a726da5b2f11d8381b26' WHERE id = 1;
 368     UPDATE users SET password = 'e727d1464ae12436e899a726da5b2f11d8381b26' WHERE id = 2;
 369     UPDATE users SET password = 'e727d1464ae12436e899a726da5b2f11d8381b26' WHERE id = 3;
 370
 371 =item *
 372
 373 Load the user/roles data:
 374
 375     mysql -ututorial myapp < myapp03_mysql.sql
 376
 377 =back
 378
 379 =back
 380
 381 =head2 PostgreSQL
 382
 383 B<TODO>
 384
 385
 386 =head1 APPENDIX 3: IMPROVED HASHING SCRIPT
 387
 388 Here is an improved SHA-1 hashing script from Gavin Henry that does
 389 not expose the passwords to "capture" on the command line.
 390
 391     #!/usr/bin/perl -w
 392     #===============================================================================
 393     #
 394     #         FILE:  enc_pass.pl
 395     #
 396     #        USAGE:  ./enc_pass.pl
 397     #
 398     #  DESCRIPTION:  Encrypt a Password using SHA-1
 399     #
 400     #      OPTIONS:  ---
 401     # REQUIREMENTS:  ---
 402     #         BUGS:  ---
 403     #        NOTES:  ---
 404     #       AUTHOR:  Gavin Henry (GH), <ghenry@suretecsystems.com>
 405     #      COMPANY:  Suretec Systems Ltd.
 406     #      VERSION:  1.0
 407     #      CREATED:  26/06/2006
 408     #     REVISION:  ---
 409     #    COPYRIGHT:  http://search.cpan.org/dist/perl/pod/perlgpl.pod
 410     #===============================================================================
 411
 412     use strict;
 413     use warnings;
 414     use Digest::SHA1;
 415     use Term::ReadKey;
 416
 417     sub get_pass {
 418         ReadMode 'noecho';
 419         chomp( my $pw = ReadLine 0 );
 420         ReadMode 'normal';
 421         return $pw;
 422     }
 423
 424     print "Enter the password to be encrypted: ";
 425     my $pass = get_pass();
 426
 427     print "\nConfirm the password: ";
 428     my $verify = get_pass();
 429
 430     if ( $pass eq $verify ) {
 431         my $sha1_enc = Digest::SHA1->new;
 432         $sha1_enc->add($pass);
 433
 434         print "\nYour encrypted password is: "
 435           . $sha1_enc->hexdigest . "\n"
 436           . "Paste this into your SQL INSERT/COPY Data.\n";
 437     }
 438     else {
 439         print "\nPasswords do not match!\n";
 440     }
 441
 442
 443
 444 =head1 AUTHOR
 445
 446 Kennedy Clark, C<hkclark@gmail.com>
 447
 448 Please report any errors, issues or suggestions to the author.  The
 449 most recent version of the Catlayst Tutorial can be found at
 450 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
 451
 452 Copyright 2006, Kennedy Clark, under Creative Commons License
 453 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).