generate: A PHP repository from walterdavis

#Scaffold Generator for MyActiveRecord and MyActionPack

This system creates a working database-backed application by reflecting over your database and generating a set of folders and static PHP files containing the basic CRUD operations for the selected tables.

This release lists stand-alone tables (not linking tables) and provides limited support for parent/child relationships and many-to-many relationships. Each model's destroy method can clean up child and related records if you choose that option in the generator form.

Version 0.5 - first public release

##ActiveRecord and MyActiveRecord Active Record is a software design pattern popularized by Martin Fowler, and taken to its logical conclusion in the Ruby on Rails framework. MyActiveRecord was written by Jake Grimley in 2006, and has been extended and tended to by Walter Davis since 2009. Rather than be a complete or perfect implementation of AR, MAR strives to be lightweight, very fast, and deliberately limited. It is extremely easy to extend.

In order to achieve this simplicity, MAR requires that you follow these simple rules when creating your models:

Each model class must have a database table named as the plural form of itself (except in lower-case, for database portability).
Each model table must have an auto-incrementing integer field as its primary key, named id by default.
Relationships between models are expressed using specially-named "foreign key" fields and join tables. (More about that below.)

##Server Requirements You will need a basic Apache server with the mod_rewrite engine installed and enabled, and AllowOverrides:all set in the server's configuration file, PHP 5.1 or better (preferably installed as a DSO in Apache 2 or mod_php in Apache 1.3), and MySQL 4.1 or better (tested on 5.1).

You will need a MySQL user with the necessary privileges to create new databases and/or tables.

The generated application uses PHP's "short open tags" feature, which may be disabled on your server. There is a configuration option in the .htaccess file which will attempt to turn this on for you, but depending on your server's basic configuration, you may need to make this change in your php.ini file instead. See the .htaccess file for instructions.

##Install and Setup To use, move the entire generate folder to a Web server, and check/change permissions on the generate/generated_code sub-folder so that your Apache/PHP process can write to that sub-folder.

Open the scaffold.php file with a text editor, and update the configuration at the top of the file to match your server. These credentials will be copied into the generated site, so you need to either run this on the same server as you intend to use to serve the final project, or change the generated config file when you deploy.

Your site files will be generated (and re-generated) within a folder named exactly the same as your database, within the generated_code directory. So if you entered the following DSN for your database: user:pass@localhost/test you would find a folder at generated_code/test containing all of your site documents and and an .htaccess file after you generate from your first table.

For bonus points, set up your Web server to host a site from generated_code/[dbname] so you can view your progress as you go.

Once you have finished the site generation process, you can move the [dbname] folder anywhere you like on your Web server, and host your site from there. Please note -- the .htaccess and _routing.php files are configured to work in the site root folder. You can change this, but by default, the site will only work when run from a dedicated hostname, as opposed to a sub-folder.

##Process Your First Table Visit scaffold.php in a browser. You should see the names of the tables in your database. Click on the first table you wish to work from to begin. The system interprets the following field types when generating form inputs:

Varchar or Char or Int will become a text input
Tinyint(1) will become a boolean (checkbox)
Text will become a textarea
Date and DateTime columns will become a text input with a special HTML classname for further processing with JavaScript
Any Date or DateTime column that ends in _at or _on will be treated as a special timestamp. If the column is named created_on or created_at, or updated_at or updated_on, it will have special setter functions in the Model's save() method.
Any column that is named [other table name in singular form]_id will be treated as a foreign key from that table
Any table which has a foreign key in another table can choose to perform cascading deletes in its destroy() method.

The id column is not editable, as it is always your primary key.

###Validations The following validations are included:

validate_regexp() Enter a regular expression, including delimiters, properly escaped. The column must match this regexp in order to pass
validate_existence() The field must not be empty to pass
validate_uniqueness_of() The field must not match the same field in any other records in the table (note -- this does not include a test for empty, combine with validate_existence() to also test for that)
validate_email() This is a combo validator, which tests for presence and format

Mix and match the validations as you like.

###Cascading Delete Dependent delete will be offered as an option if the table includes a field named [other table in singular form]_id. If so, checking this option will include the logic to clean up dependent records from that other table. For example, if you delete a Blog Post, all of the Comments with a matching post_id will be deleted at the same time. You don't need to choose this if you don't need it.

##Generate the Site When you press the Generate button, all of your files will be created and listed. Click the Start Over link to select another table and begin this process again.

Once you have generated the files for a particular table, they will not be overwritten unless you check the "Overwrite Existing Files" checkbox at the bottom of the screen. If you make changes to your database (add, remove or change columns) you will need to check this option to get a fresh set of interface files. I strongly recommend that you place the generated_code folder in version control so you can merge your edits or roll back any overwrites.

##Install the Site Move the generated folder [dbname] into a new location in your Web server, and update your Apache configuration files to serve your application from that new location. The name of the containing folder is not important, and you can copy the contents of the folder into your htdocs folder or local equivalent. Just be sure you copy the (hidden) .htaccess file when you do.

You can edit any of the files, they are all static and do not rely on any magic to work correctly. File naming is however very important. Just as in Rails or its various clones, the location and name of files is used to link up the various parts of the Model / View / Controller stack.

The content of the Model, View and Controller files is just a suggestion to get you started. Feel free to add or delete methods to the controller, which will be mapped automatically to matching URLs. [model plural]/[controller method]/[id] is the basic idea. This strategy is set in the _routing.php file, and can be modified there.

walterdavis/generate