Laravel Doctrine Jetpack

A set of productivity boosting helpers to make life with Laravel Doctrine simpler and faster.

Installation

This package strictly requires php >= 7.4.

Require the package using Composer.

composer require szainmehdi/laravel-doctrine-jetpack

Laravel automatically discovers the package. No additional steps are necessary.

Usage

Generators

This package includes a few generators that allow you to speed up your workflow when it comes to writing entities and mapping classes using Laravel Doctrine.

Entity Generator

Generate a new Doctrine entity using the included stub by running the following artisan command:

php artisan make:entity MyEntity

By default, this will create a new file in app/Entities called MyEntity.php, like so:

<?php declare(strict_types=1);

namespace App\Entities;

use Illuminate\Contracts\Support\{Arrayable, Jsonable};
use JsonSerializable;
use Ramsey\Uuid\{Uuid, UuidInterface};
use Zain\LaravelDoctrine\Jetpack\Serializer\SerializesAttributes;

class MyEntity implements Arrayable, Jsonable, JsonSerializable
{
    use SerializesAttributes;

    protected UuidInterface $id;

    public function __construct()
    {
        $this->id = Uuid::uuid1();
    }

    public function getId(): string
    {
        return $this->id->toString();
    }
}

Fluent Mapping Generator

This package comes with a generator for Laravel Doctrine's Fluent mapping driver, a very Laravel-like way of writing your Doctrine mappings.

The included command takes a target entity as an argument and generates a mapping file.

php artisan make:mapping MyEntity

By default, this will create a new file in app/Database/Doctrine/Mappings/ called MyEntityMapping.php, like so:

<?php declare(strict_types=1);

namespace App\Database\Doctrine\Mappings;

use App\Entities\MyEntity;
use LaravelDoctrine\Fluent\EntityMapping;
use LaravelDoctrine\Fluent\Fluent;

class MyEntityMapping extends EntityMapping
{
    public function mapFor()
    {
        return MyEntity::class;
    }

    public function map(Fluent $map)
    {
        $map->uuidPrimaryKey();
        // ...
        $map->timestamps();
    }
}

Generate a Fluent Mapping class for a Value Object (Embeddable).

php artisan make:mapping MyValue --value

By default, this will create a new file in app/Database/Doctrine/Mappings/Values/ called MyValueMapping.php.

FlushEntityManager Middleware

Simplify the process of actually persisting your entities to the database using the included middleware.

Add the middleware to your app/Http/Kernel.php file like so:

class Kernel extends HttpKernel
{
    // ...

    protected $middleware = [
        // ...
        \Zain\LaravelDoctrine\Jetpack\Middleware\FlushEntityManager::class,
    ];
}

Helpers

Entity Serialization

This package also includes a helper trait that allows you to make your entities (and potentially any other class) serializable to JSON or an array with just a single line.

use Illuminate\Contracts\Support\Arrayable;
use Illuminate\Contracts\Support\Jsonable;
use JsonSerializable;
use Zain\LaravelDoctrine\Jetpack\Serializer\SerializesAttributes;

class MyEntity implements Arrayable, Jsonable, JsonSerializable
{
    // Add this trait to your entities
    use SerializesAttributes;
}

Note: for the best experience with Laravel, I recommend having your Entity classes implement the three standard interfaces in the example above. This is not necessary but it will allow you to simply return your model from a controller, or inspect it in tinker. (I am not recommending doing the former, but it is definitely useful for debugging in a pinch.)

Customization & Configuration

This package allows you to easily customize almost every aspect of the generators. Get started by publishing the config file.

php artisan vendor:publish --tag jetpack-config

This will create a file in your config directory called jetpack.php. Edit this file to change the default namespace for your Entities, Value Objects, and Mapping classes.

---

For advanced customization, this package allow you to customize the built-in stub files to your own needs.

First, ensure you've already published the config file in the step above. Next, publish the stubs using the following command.

php artisan vendor:publish --tag jetpack-stubs

This will write the stub files to resources/jetpack/stubs. Feel free to edit the files as you please, but keep the placeholder names intact.

Finally, update config/jetpack.php:

return [
    'generators' => [
        'stubs_directory' => resource_path('jetpack/stubs/'),
        // ...
    ],
    // ...
];

Development

All contributions are welcome. Found a bug? Open an issue in Github, or even better, submit a Pull Request.

Running Tests

Check out the project locally, and run:

composer install

composer test

# or, using docker
docker-compose run --rm php composer test