PropelORM is an open-source Object-Relational Mapping (ORM) for PHP5. It allows you to access your database using a set of objects, providing a simple API for storing and retrieving data.
In this article, I’ll explain how to use PropelORM in an existing PHP project.
Download and installation
If your project is using Git:
- go to the root of the project:
- download Propel as a submodule of your project (if you want to download Propel in
git submodule add https://github.com/propelorm/Propel.git application/plugins/propel
- commit the submodule:
git commit -m "Added PropelORM as a submodule"
If your project doesn’t use Git:
- go to the subdirectory
application/pluginsin your project and create a directory
cd myproject/application/plugins mkdir propel
- download the latest version of PropelORM as a ZIP file or a TAR.GZ file
- extract the content of the archive in the newly created
PropelORM uses a script to generate the mapping code. You have to create a symbolic link to the script in the
application directory of your project:
cd myproject/application ln -s plugins/propel/generator/bin/propel-gen propel-gen
Create a file
myproject/application/build.properties which will contain the basic information about the project and DB connection:
cd myproject/application touch build.properties
This file contains:
# Project name propel.project = project_name # Connection parameters propel.database = mysql # If you want to automatically update the DB, set the following values: propel.database.url = mysql:host=db_host;dbname=db_name propel.database.user = db_user propel.database.password = db_password
DB schema creation
The DB schema is defined in the file
myproject/application/schema.xml. You can find on the PropelORM documentation everything you need to build your DB schema: creation of the file and schema format.
Once these files are created and contain the correct data, you can use the
propel-gen script to generate the mapping source.
To generate the Object Model
cd myproject/application ./propel-gen om
To generate the SQL file
cd myproject/application ./propel-gen sql
To update the DB with the SQL file (need the DB connection info)
cd myproject/application ./propel-gen insert-sql
Runtime connection settings creation
For PropelORM to be able to be linked to the DB when running, you’ll need to create a configuration file that defines the DB connection.
cd myproject/application touch runtime-conf.xml
This file must contains a configuration like:
<?xml version="1.0" encoding="UTF-8"?> <config> <propel> <datasources default="project_name"> <datasource id="project_name"> <adapter>mysql</adapter> <!-- sqlite, mysql, mssql, oracle, or pgsql --> <connection> <dsn>mysql:host=db_host;dbname=db_name</dsn> <user>db_user</user> <password>db_password</password> </connection> </datasource> </datasources> </propel> </config>
The content of the file is described in the PropelORM documentation: Writing The XML Runtime Configuration.
Notice how the id attribute of the
<datasource> tag matches the connection name defined in the
<database> tag of the
schema.xml. This is how Propel maps a database description to a connection.
To build the runtime conf:
cd myproject/application ./propel-gen convert-conf
To run the 3 commands (om, sql, and convert-conf):
cd myproject/application ./propel-gen
Including PropelORM in your PHP code
Include in a setup/config file:
<?php // Include the main Propel script require_once '/path/to/propel/runtime/lib/Propel.php'; // Initialize Propel with the runtime configuration Propel::init("/path/to/bookstore/build/conf/rgcms-conf.php"); // Add the generated 'classes' directory to the include path set_include_path("/path/to/bookstore/build/classes" . PATH_SEPARATOR . get_include_path());
Using PropelORM inside your project
You can find how to use PropelORM on the official documentation.