README

A trait that allows a Laravel project's Eloquent models to cast attribute values to native PHP variable types.

Background
Installation and Requirements
Usage
Notes
Bugs, Suggestions and Contributions
Copyright and License

Background: Why Do I Need This?

For some database drivers, all the attributes you get back from a query are returned as strings, even when the underlaying column-type is INTEGER or FLOAT or BOOLEAN.

Rather than have to use these "integer-looking" strings, etc., and rely on PHP's type-juggling, this trait will cast those attribute values to the proper native PHP variable type automagically for you.

This is also going to be very handy if you are, say, building an API and would like to just return JSON-versions of Eloquent models. Using this trait, all the JSON elements are going to be the right type for consumers of your API -- instead of all strings -- saving them type-juggling on their end.

Note: I believe if you are using the mysqlnd drivers in your PHP installation, then you don't need this trait as mysqlnd handles this type casting for you. Try it out by doing a var_dump($model->getKey()). If it shows that the value is an integer, you don't need this package. If it shows it's a string, read on.

Installation & Requirements

In your project's composer.json file:

"require": {
    "cviebrock/eloquent-typecast": "1.*"
}

In your project's models (or your own base model):

use Cviebrock\EloquentTypecast\EloquentTypecastTrait;

class MyModel {

    use EloquentTypecastTrait;

    // Define the attributes you want typecast here
    protected $cast = array(
        'id'         => 'integer',
        'price'      => 'float',
        'is_awesome' => 'boolean'
    );

    ...

}

That's it. No service providers or facades required. Because it's a trait, however, you will need to be running PHP 5.4 or later.

Usage

Anytime you request an attribute listed in the $cast array, it will be converted from the (usually) string that your database returned into a the native PHP variable type you specified.

The keys of the $cast array are the attribute (i.e. column) names, and the values are the types you want to cast to. Anything supported by PHP's settype() function is valid ... although casting to arrays, objects, or null could be problematic.

If you set the $castOnSet property on your model to true, then setting an attribute that's in the $cast array will typecast that value before setting it. For example:

class MyModel {

    use EloquentTypecastTrait;

    protected $castOnSet = true;

    protected $cast = array(
        'price'      => 'float',
    );

}

$myModel = MyModel::find(1);

$price = Input::get('price');  // this will be a string
$myModel->price = $price;      // the string is cast to a float before setting;

In general, this setting isn't really necessary as Laravel and most databases will handle the string-to-column-type conversion for you on save. However, maybe there are cases where it's useful, so it's added for "feature completion".

Notes

Because of the way the trait works, you should make sure that your $cast array does not include:

relations
attributes for which you already have a custom mutator
attributes using Eloquent's date mutation

$model->toArray() triggers the casting as well. $model->getAttributes(), however, does not. It returns the raw values from the query (not even the date mutation).

Bugs, Suggestions and Contributions

Please use Github for bugs, comments, suggestions.

Fork the project.
Create your bugfix/feature branch and write your (well-commented) code.
Create unit tests for your code:
- Run composer install --dev in the root directory to install required testing packages.
- Add your test methods to eloquent-typecast/tests/TypecastTest.php.
- Run vendor/bin/phpunit to the new (and all previous) tests and make sure everything passes.
Commit your changes (and your tests) and push to your branch.
Create a new pull request against the develop branch.

Please note that you must create your pull request against the develop branch.

Copyright and License

Eloquent-Typecast was written by Colin Viebrock and released under the MIT License. See the LICENSE.md file for details.

cviebrock / eloquent-typecast

Maintainers

Details