Skip to content

Latest commit

 

History

History
69 lines (50 loc) · 5.92 KB

1. Setup.md

File metadata and controls

69 lines (50 loc) · 5.92 KB
Raw

PHPFUI\ORM Setup

PHPFUI\ORM takes a SQL first approach to models. You update the SQL schema first, then generate models from the SQL schema. You can use migrations to change the schema (recommended), or modify the schema by hand.

Database Schema Requirements

PHPFUI\ORM needs a strictly normalized database structure to work. The following conditions must be met:

  • Table primary keys must be in the form of (table name)(id suffix). Examples would be member.memberId, purchase_order.purchase_order_id or even OrderDetail.OrderDetailId
  • Consistant case is required for field and table names.
  • Field names referencing other table's primary key must match the referenced table primary id field name. Example: purchase_order_detail.purchase_order_id would reference the parent purchase_order record.

Models Defined

PHPFUI\ORM mandates the following models and separate namespaces:

  • Record - represents a record from a table
  • Table - represents the entire SQL table
  • Definition - describes the fields in the table
  • Validation (optional) - defines validation rules for each field

Once generated, the Record, Table and Validation models will not be overwritten by the generation tools. Developers can add any logic to these classes they desire.

The Definition models should only be modified by the generation tools and not updated by hand.

Deletion of unused models should be done manually when the table is removed from the schema.

PHP Class Naming Conventions

All PHPFUI\ORM classes and namespaces use StudlyCase naming conventions. SQL table names are used the generate the PHP class names. Case is preserved except the first letter is the converted to upper case. Table names with underscores are converted to StudlyCase and underscores are removed. Field names are not affected and left unchanged.

Each table will generate 3 classes (4 if validators are generated) with the same class name, but in the specified namespaces (see below). Definition and Validation namespaces are children of the Record namespace.

Configuration

PHPFUI\ORM needs the following information to work with your code:

  • Your Namespace Root - \PHPFUI\ORM::$namespaceRoot, Default: Root namespace directory (__DIR__ . '/../..')
  • The Record Model Namespace - \PHPFUI\ORM::$recordNamespace, Default: 'App\Record'
  • The Table Model Namespace - \PHPFUI\ORM::$tableNamespace, Default: 'App\Table'
  • The Migration Namespace - \PHPFUI\ORM::$migrationNamespace, Default: 'App\Migration'
  • Primary Key Suffix - \PHPFUI\ORM::$idSuffix, Default: 'Id'

If you are unable to use the defaults, it is recommended setting the\PHPFUI\ORM static fields immediately after your autoloader and before you open a database connection:

Example Setup

PHPFUI\ORM uses PHP's PDO model exclusively. You must create a valid PDO connection with the \PHPFUI\ORM\PDOInstance class and pass it to \PHPFUI\ORM::addConnection() to allow access to the database.

include 'vendor/autoload.php';
\PHPFUI\ORM::$namespaceRoot = __DIR__;
\PHPFUI\ORM::$recordNamespace = 'App\\Model\\Record';
\PHPFUI\ORM::$tableNamespace = 'App\\Model\\Table';
\PHPFUI\ORM::$migrationNamespace = 'App\\DB\\Migration';
\PHPFUI\ORM::$idSuffix = '_id';
\PHPFUI\ORM::addConnection(new \PHPFUI\ORM\PDOInstance('sqlite:northwind.db'));

Migrations

Add the migrations to your migration namespace. Migration classes must be numbered starting at 1 in the format of Migration_X where X is the migration id. Breaks in the numbering sequence are not allowed.

Numbered migrations ensure all developers on a team run the migrations in the same order. This solves a major problem with time stamped migration in other popular ORM systems. Time stamping a migration means migrations may run in different orders by different developers when working on independent branches. Migrations can also be applied to different enviornments in different orders depending on branch merging and deployments. Numbered migrations are resolved at merge time and all developers have to apply them in the correct order. Developers are responsible for making sure they are on the correct migration before switching to new branches.

Running Migrations

Use the \PHPFUI\ORM\Migrator class to update the schema to any level. You can migrate up or down individually or in groups.

Generating Models

Once you have a compatible schema, or have modified a schema, you need to generate code. Use the \PHPFUI\ORM\Tool\Generate\CRUD class to generate all or individual models. Check out the scripts folder for an example.

Once Record and Table models are generated, they will not be overwritten by the generation tools. Feel free to add methods by hand for your application needs.

You should regenerate models when ever you update this library. Generation will only ever overwrite files in the Definition namespace, which should not be edited by hand. Record, Table, and Validation namespaces will only be generated if the file is missing.

Validation

You can also generate initial validators with the \PHPFUI\ORM\Tool\Generate\Validator class. Once generated, you should modify by hand for your application.

Validation rules can be found here: \PHPFUI\ORM\Validator.