Download the PHP package csrdelft/orm without Composer
On this page you can find all versions of the php package csrdelft/orm. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package orm
Short Description The creatively named object-relational mapping library for csrdelft.nl
License MIT
Homepage https://csrdelft.github.io/orm
Informations about the package orm
C.S.R. Delft ORM
A simple object-relational mapper for PHP. We currently use this library in production on csrdelft.nl.
Installation
Install with composer
Before the ORM can be used the cache and database must be initialized. The memcache needs a unix socket or host and port and the database and database admin need a host, database, username and password. After this any model has access to the database.
Usage
The ORM relies on models and entities. Models are classes which interface with the database. Entities are data classes which contain a definition for the database tables. This document will give a brief overview of the basic things you need to know in order to get started.
Entity
An entity is an object containing data, like for instance a car, person, etc.
When you want to save an entity to the database, you'll have to extend the class
PersistentEntity
. An entity must contain a few variables, which are discussed
below. An entity must only contain logic about itself, not logic about other classes
or about other instances of the same entity. This should be in the Model (or the controller which is
not part of this library).
Entities are placed in the folder model/entity/
and are named EntityName.php
.
Variables in an entity
For each attribute of an entity there must be a public variable. These will be used by the model when loading from a database.
$table_name
The name of the table in the database.
$persistent_attributes
An array of attributes of the entity, mapped to a type.
A Type is an array, with the following values.
- 0: Type from
T
(PersistentAttributeType.enum
) - 1: Is this variable nullable?
- 2: If 0 is
T::Enumeration
, the enum class (extendsPersistentEnum
). Else 'extra', for instanceauto_increment
or comment.
$primary_key
An array with the full primary key.
$computed_attributes
An array of computed attributes. This maps these attributes to a function and adds them to jsonSerialize
Example
model/entities/Car.php
Model
A model has to extend the PersistenceModel
class. A model is the owner of a
specific entity. A model can be accessed everywhere with the public static
instance()
method. This should however be avoided where possible.
Models should be placed in model/
.
Variables in a model
A model has a few static variables which must be defined.
ORM
The constant ORM
defines which entity this model is the owner of. This is a string or class.
$default_order
This is the default value to use for the order when selecting from the database.
Functions in a model
The following functions can be used on a model
find($criteria, $criteria_params, ...) : PersistentEntity[]
Find entities in the database filtered on criteria. The syntax for this should be familiar if you
ever worked with PDO in PHP. The $criteria
is the WHERE
clause of the underlying select statement, you can
put ?
's here where variables are. The criteria params are where you fill these variables. Criteria
params are automatically filtered and safe for user input.
count($criteria, $criteria_params) : int
Count the number of entities which pass the criteria, same as find(..)
. Creates statements like
SELECT COUNT(*) ...
which are faster than counting in PHP.
exists($entity) : boolean
Check whether or not an entity exists in the database.
create($entity) : string
Save a new entity into the database. Returns the id of the inserted entity.
update($entity) : int
Store an entity in the database, replacing the entity with the same primary key.
delete($entity) : int
Delete an entity from the database.
Example
model/CarModel.php
index.php
Database update
This orm can check the models for you. To enable this feature you need to define
the global constant DB_CHECK
as true
. After that you can check the DatabaseAdmin for
any updated tables. This only checks tables which are in use and must be done
after all models are used. It is also possible to enable automatically updating
the database by defining the global constant DB_MODIFY
as true
. This will
update tables according to your models. This will not try to migrate data, so
be careful. DB_MODIFY
will not drop tables. for this you will need to define
DB_DROP
as true
.
JSON fields
By using T::JSON, a database field can be mapped to an array or object. On save, data is serialized to JSON and can later be deserialized. In the example the $reviews property is a JSON field.
To prevent remote code execution only allowed classes can be (de)deserialized. In the third element of the attribute defintion the list of allowed classes should be specified. Also null can be passed to allow all classes.
Database transactions
To wrap multiple database calls in a transaction you can use Database::transaction(Closure)
.
This function wraps another function in a database transaction. Any exception thrown causes the
transaction to be rolled back. If the database is in a transaction this function will just call the
Closure
without trying to create a new transaction.
Dependency Injection
You can provide your own ContainerInterface
to DependencyManager
, this container will be used for everything. You still need to provide the container with instances of Database
, DatabaseAdmin
and OrmMemcache
.
It is also possible to leverage the dependency injection provided by the orm. The orm does a very simple way of dependency injection. When a instance of a model is created is created
it tries to lookup any dependencies which extend DependencyManager
if they are found they are wired into the
model and available for use. There can only be one version of a model and this is kept track of in DependencyManager
.
Example
All versions of orm with dependencies
psr/container Version ^1.0
zumba/json-serializer Version ^2.2
ext-pdo Version *
ext-json Version *