Vendor lock
This commit is contained in:
197
vendor/j4mie/paris/docs/querying.rst
vendored
Normal file
197
vendor/j4mie/paris/docs/querying.rst
vendored
Normal file
@ -0,0 +1,197 @@
|
||||
Querying
|
||||
========
|
||||
|
||||
Querying allows you to select data from your database and populate
|
||||
instances of your model classes. Queries start with a call to a static
|
||||
*factory method* on the base ``Model`` class that takes a single
|
||||
argument: the name of the model class you wish to use for your query.
|
||||
This factory method is then used as the start of a *method chain* which
|
||||
gives you full access to `Idiorm`_\ ’s fluent query API. **See Idiorm’s
|
||||
documentation for details of this API.**
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$users = Model::factory('User')
|
||||
->where('name', 'Fred')
|
||||
->where_gte('age', 20)
|
||||
->find_many();
|
||||
|
||||
You can also use the same shortcut provided by Idiorm when looking up a
|
||||
record by its primary key ID:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$user = Model::factory('User')->find_one($id);
|
||||
|
||||
If you are using PHP 5.3+ you can also do the following:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$users = User::where('name', 'Fred')
|
||||
->where_gte('age', 20)
|
||||
->find_many();
|
||||
|
||||
This does the same as the example above but is shorter and more readable.
|
||||
|
||||
|
||||
The only differences between using Idiorm and using Paris for querying
|
||||
are as follows:
|
||||
|
||||
1. You do not need to call the ``for_table`` method to specify the
|
||||
database table to use. Paris will supply this automatically based on
|
||||
the class name (or the ``$_table`` static property, if present).
|
||||
|
||||
2. The ``find_one`` and ``find_many`` methods will return instances of
|
||||
*your model subclass*, instead of the base ``ORM`` class. Like
|
||||
Idiorm, ``find_one`` will return a single instance or ``false`` if no
|
||||
rows matched your query, while ``find_many`` will return an array of
|
||||
instances, which may be empty if no rows matched.
|
||||
|
||||
3. Custom filtering, see next section.
|
||||
|
||||
You may also retrieve a count of the number of rows returned by your
|
||||
query. This method behaves exactly like Idiorm’s ``count`` method:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$count = Model::factory('User')->where_lt('age', 20)->count();
|
||||
|
||||
A note on PSR-1 and camelCase
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
All the methods detailed in the documentation can also be called in a PSR-1 way:
|
||||
underscores (_) become camelCase. Here follows an example of one query chain
|
||||
being converted to a PSR-1 compliant style.
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
// documented and default style
|
||||
$count = Model::factory('User')->where_lt('age', 20)->find_one();
|
||||
|
||||
// PSR-1 compliant style
|
||||
$count = Model::factory('User')->whereLt('age', 20)->findOne();
|
||||
|
||||
As you can see any method can be changed from the documented underscore (_) format
|
||||
to that of a camelCase method name.
|
||||
|
||||
.. note::
|
||||
|
||||
In the background the PSR-1 compliant style uses the `__call()` and
|
||||
`__callStatic()` magic methods to map the camelCase method name you supply
|
||||
to the original underscore method name. It then uses `call_user_func_array()`
|
||||
to apply the arguments to the method. If this minimal overhead is too great
|
||||
then you can simply revert to using the underscore methods to avoid it. In
|
||||
general this will not be a bottle neck in any application however and should
|
||||
be considered a micro-optimisation.
|
||||
|
||||
As `__callStatic()` was added in PHP 5.3.0 you will need at least that version
|
||||
of PHP to use this feature in any meaningful way.
|
||||
|
||||
Getting data from objects, updating and inserting data
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The model instances returned by your queries now behave exactly as if
|
||||
they were instances of Idiorm’s raw ``ORM`` class.
|
||||
|
||||
You can access data:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$user = Model::factory('User')->find_one($id);
|
||||
echo $user->name;
|
||||
|
||||
Update data and save the instance:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$user = Model::factory('User')->find_one($id);
|
||||
$user->name = 'Paris';
|
||||
$user->save();
|
||||
|
||||
To create a new (empty) instance, use the ``create`` method:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$user = Model::factory('User')->create();
|
||||
$user->name = 'Paris';
|
||||
$user->save();
|
||||
|
||||
To check whether a property has been changed since the object was
|
||||
created (or last saved), call the ``is_dirty`` method:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$name_has_changed = $person->is_dirty('name'); // Returns true or false
|
||||
|
||||
You can also use database expressions when setting values on your model:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$user = Model::factory('User')->find_one($id);
|
||||
$user->name = 'Paris';
|
||||
$user->set_expr('last_logged_in', 'NOW()');
|
||||
$user->save();
|
||||
|
||||
Of course, because these objects are instances of your base model
|
||||
classes, you can also call methods that you have defined on them:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
class User extends Model {
|
||||
public function full_name() {
|
||||
return $this->first_name . ' ' . $this->last_name;
|
||||
}
|
||||
}
|
||||
|
||||
$user = Model::factory('User')->find_one($id);
|
||||
echo $user->full_name();
|
||||
|
||||
To delete the database row associated with an instance of your model,
|
||||
call its ``delete`` method:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
$user = Model::factory('User')->find_one($id);
|
||||
$user->delete();
|
||||
|
||||
You can also get the all the data wrapped by a model subclass instance
|
||||
using the ``as_array`` method. This will return an associative array
|
||||
mapping column names (keys) to their values.
|
||||
|
||||
The ``as_array`` method takes column names as optional arguments. If one
|
||||
or more of these arguments is supplied, only matching column names will
|
||||
be returned.
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
<?php
|
||||
class Person extends Model {
|
||||
}
|
||||
|
||||
$person = Model::factory('Person')->create();
|
||||
|
||||
$person->first_name = 'Fred';
|
||||
$person->surname = 'Bloggs';
|
||||
$person->age = 50;
|
||||
|
||||
// Returns array('first_name' => 'Fred', 'surname' => 'Bloggs', 'age' => 50)
|
||||
$data = $person->as_array();
|
||||
|
||||
// Returns array('first_name' => 'Fred', 'age' => 50)
|
||||
$data = $person->as_array('first_name', 'age');
|
||||
|
||||
.. _Idiorm: http://github.com/j4mie/idiorm/
|
||||
Reference in New Issue
Block a user