Download the PHP package somnambulist/laravel-doctrine-behaviours without Composer
On this page you can find all versions of the php package somnambulist/laravel-doctrine-behaviours. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download somnambulist/laravel-doctrine-behaviours
More information about somnambulist/laravel-doctrine-behaviours
Files in somnambulist/laravel-doctrine-behaviours
Package laravel-doctrine-behaviours
Short Description Alternative Doctrine behaviours for laravel-doctrine extensions. Provides blamable, timestampable and universally identifiable.
License MIT
Informations about the package laravel-doctrine-behaviours
Replaced with https://github.com/dave-redfern/somnambulist-domain
This project has been replaced with a generic domain library that combines several packages into one for easier maintenace. Please note that many of these behaviours have since been removed entirely.
Behaviours for Laravel-Doctrine ORM
Adds some very common traits, contracts and event subscribers that can be used with the Laravel-Doctrine ORM package, replacing Gedmo Blameable and Timestampable as well as a UUID pre-persist behaviour.
This library is very opinionated on naming and Doctrine config. Each of the behaviours and all the traits work on the basis that Doctrine is running with configuration files and not annotations. The names of each field are set within the traits.
Requirements
- PHP 7+
- laravel 5.3+
- laravel-doctrine/orm
BC Breaks
1.0.0
Earlier versions of this package featured Sluggable and Uuid listeners, these have since been removed as the UUID and slug should be generated by the Application before persisting / flushing your entities.
In addition, many of the interfaces have either redefined, or removed entirely the requirement for setters, as many of the property changes should be made through controlled state transitions. For example: timestamps should be initialised and createdAt not readily modifiable; blamable should set the creator but not allow modification, UUIDs should never change after the fact.
The full list of changes are:
- Blamable removal of setCreatedBy, setUpdatedBy added blameCreator() blameUpdater() ** trait implements the interface and blameCreator() does not allow changes
- NumericallySortable removal of setOrdinal added updateSortingOrder()
- Publishable removal of setPublishedAt trait updated to remove setPublishedAt() method
- Sluggable removal of setSlug removal of SluggableEventSubscriber
- Timestampable removal of setCreatedAt, setUpdatedAt added initializeTimestamps() updateTimestamps() ** trait implements the interface and initializeTimestamps() does not reset dates
- UniversallyIdentifiable removal of setUuid removal of UuidEventSubscriber
- Versionable removal of setVersion changed initial value in trait to 0 ** incrementVersion is now called on prePersist as well as on preUpdate
In the case of unique identifiers such as slug and UUID these should be generated for the entity and passed in during first creation.
Installation
Install using composer, or checkout / pull the files from github.com.
- composer install somnambulist/laravel-doctrine-behaviours
Enabling in Doctrine
To enable the behaviours, add each EventSubscriber to the config/doctrine.php file:
'managers' => [
'default' => [
'events' => [
'subscribers' => [
\Somnambulist\Doctrine\EventSubscribers\BlamableEventSubscriber::class,
\Somnambulist\Doctrine\EventSubscribers\TimestampableEventSubscriber::class,
\Somnambulist\Doctrine\EventSubscribers\VersionableEventSubscriber::class,
]
],
]
],
- Note: you only need to add the subscribers you actively want to use.
To ensure Carbon is used in your entities, and the following to the types:
'custom_types' => [
'date' => \Somnambulist\Doctrine\Types\DateType::class,
'datetime' => \Somnambulist\Doctrine\Types\DateTimeType::class,
'datetimetz' => \Somnambulist\Doctrine\Types\DateTimeTzType::class,
'time' => \Somnambulist\Doctrine\Types\TimeType::class,
],
- Note: the type overrides are required when using TimestampableEventSubscriber.
- Note: these behaviours are intended to be used with meta-data files not annotations!
JsonCollection
To enable the JsonCollectionType, add the following to the custom_types in the doctrine.php:
'json_collection' => \Somnambulist\Doctrine\Types\JsonCollectionType::class,
This type hydrates a JSON encoded string into an ArrayCollection object instead of a standard PHP array. Depending on use case this may be more useful and it allows consistent collection handling within your Entity.
To use the JsonCollection, in your mapping files set the type to: json_collection
:
// simple example
Entity:
fields:
properties:
type: json_collection
Then initialise the propoerty in your entities constructor.
- Note: if the JSON data is empty, an empty ArrayCollection will be used.
- Note: this does not replace the standard json_array; you can use both.
Service Provider
A Laravel service provider is included that allows defining repositories in a config file. Add the service provider to your main app.php - after the DoctrineServiceProvider.
\Somnambulist\Doctrine\Providers\BehavioursServiceProvider::class,
Publish the vendors information, and two new config files will be added:
- config/doctrine_behaviours.php
- config/doctrine_repositories.php
Behaviours contains settings for the make:entity
console command that makes it
easier to add a new entity and repository.
Repositories allows you to configure repositories so they can be type-hinted and resolved by the dependency injection container (auto-wiring).
The following options are required:
- repository - the repository class, can be EntityRepository::class
- entity - the class name of the entity the repository is for
The following are optional:
- alias - a shorter alias e.g. app.user.repository
- tags - any tags to add to the reference in the container e.g.
[ 'repository' ]
- em - an alternative entity manager that manages this entity e.g. 'my_manager'
Behaviours / Traits
Blamable
Blamable adds createdBy and updatedBy and then attempts to set the name of the User who performed the create/update. This is extracted from the auth()->user() object. The User object is checked in turn for one of the following:
- UUID (UuidContract / getUuid)
- Username (getUsername)
- Email (getEmail)
- Id (getId)
If the User (somehow) does not implement any of those, the class and identifier are pulled and attempted to be located from a Doctrine repository and then the same check is made again on the found entity.
If there is no user a default is applied: 'system'
This can be overridden by setting the environment value: DOCTRINE_BLAMABLE_DEFAULT_USER.
To add Blamable support, ensure your entity implements the Blamable contract. A trait is provided that adds the appropriate methods:
use Somnambulist\Doctrine\Contracts\Blamable as BlamableContract;
use Somnambulist\Doctrine\Traits\Blamable;
class MyEntity implements BlamableContract
{
use Blamable;
}
Be sure to update your mapping files to include the fields:
fields:
createdBy:
type: string
length: 36
updatedBy:
type: string
length: 36
These fields should be at least 36 characters long as UUIDs may be used with them.
Sluggable
Sluggable adds getSlug i.e. a URL friendly text representation of the name. A trait is included implementing the property and method.
Example usage:
use Somnambulist\Doctrine\Contracts\Sluggable as SluggableContract;
use Somnambulist\Doctrine\Traits\Sluggable;
class MyEntity implements SluggableContract
{
use Sluggable;
}
Mapping file fields:
fields:
slug:
type: string
length: 255
You should add a unique constraint to the slug since they should be unique.
Note: as slugs should be unique, your application code should generate them.
Timestampable
Timestampable adds createdAt / updatedAt fields and persistence to your entities. This extension uses Carbon internally (just like Laravels Eloquent). It is not necessary to populate these fields as they will be automatically set by the event subscriber. As Carbon is used internally, the type mappings must be added to the config/doctrine.php file.
To add timestampable, implement the contract and optionally include the trait:
use Somnambulist\Doctrine\Contracts\Timestampable as TimestampableContract;
use Somnambulist\Doctrine\Traits\Timestampable;
class MyEntity implements TimestampableContract
{
use Timestampable;
}
Then add the following to your entity mapping files:
fields:
createdAt:
type: datetime
updatedAt:
type: datetime
Now your entities will be tagged with the date/time they are created/updated.
Note: the default timezone is used. Be sure to set this before using. It is recommended to set your PHP default timezone to UTC, and then translate in the UI.
Universally Identifiable
UniversallyIdentifiable adds a UUID field to your entity.
UUIDs should be generated by an appropriate uuid library (e.g.: ramsey/uuid). It is recommended to use UUIDv4 random identifiers, unless you require re-generating UUIDs for the same initial value.
Like the other behaviours to use UniversallyIdentifiable, implement the contract and optionally use the trait:
use Somnambulist\Doctrine\Contracts\UniversallyIdentifiable as UniversallyIdentifiableContract;
use Somnambulist\Doctrine\Traits\UniversallyIdentifiable;
class MyEntity implements UniversallyIdentifiableContract
{
use UniversallyIdentifiable;
}
This will ensure that this entity will be uniquely identifiable in any system - very useful when exposing entities in an API.
Be sure to add a UUID field definition to your entity mapping files:
uniqueConstraints:
uniq_table_name_here_uuid:
columns: [ uuid ]
fields:
uuid:
type: guid
It is a good idea to add a unique constraint to the UUID field just in case.
Note: that when using UUIDs you should ensure that this is a requirement in the constructor of your entity.
Additional: you may wish to use ramsey/uuid-doctrine
so that UUIDs are always hydrated as
objects. In this instance set the type: to "uuid" and ensure your entity uses UuidInterface
as the type hint.
Versionable
Versionable adds a simple "version" property that is incremented on each update. The trait sets the default (un-persisted) value to 0 (zero) with prePersist raising this to 1 (one).
Be sure to add the following to you mapping files:
fields:
version:
type: integer
The listener will then increment the version every time the entity is updated.
Others
In addition to the main behaviours there are several additional contracts / traits:
- Identifiable - adds id / getId
- Nameable - adds name / getName
- NumericallySortable - adds ordinal / getOrdinal / updateSortingOrder
- Publishable - adds publishedAt / getPublishedAt / isPublished / publishAt / unPublish
- IdentifiableWithTimestamps - Identifiable, Timestampable
- Trackable - Identifiable, Nameable, Blamable, Timestampable
- GloballyTrackable - Identifiable, Nameable, Blamable, Timestampable, UniversallyIdentifiable
NumericallySortable adds a simple "ordinal" field to allow records to be sorted by an incrementing integer value. This needs to be manually tracked in your entities e.g.: on add/remove against a colection add a "renumber" method call that will iterate and re-number the items in the collection. A simple CanRenumberCollection interface/trait is included but you may need something more sophisticated.
Trackable / GloballyTrackable wrap up the other traits / contracts providing a convenient way to add everything either as an internal entity (Trackable) or a potentially externally facing entity (GloballyTrackable).
MakeEntityCommand
A helper command has been added for quickly generating the entity stub, repository and a repository interface. This command presumes that your app folder structure will follow:
- app/Contracts/*
- app/Repositories/*
- app/Support/*
The entity class will be created wherever the classname is set e.g.: App\Entities\MyEntity will be created in app/Entities. If your base namespace is e.g: SomeProject\SomeModule, and the entity name is SomeProject\SomeModule\Entities\MyEntity, the path will be: app/Entities.
The command will create an AppEntityRepository if it does not already exist.
To use the command, add it to the list of commands in your Console/Kernel.php file. Then you can call it using:
php artisan make:entity 'App\Entities\MyEntity'
Optionally you can add various options to add behaviour:
php artisan make:entity 'App\Entities\MyEntity' -tps
Will make the entity Trackable, Publishable and Sluggable. Not all options can be used together. If you select an in-compatible set of options, you will receive an error.
This command can be extended to add other options. Simple override the behaviourOptionMappings
Links
All versions of laravel-doctrine-behaviours with dependencies
laravel-doctrine/orm Version 1.*
nesbot/carbon Version ~1.19
ramsey/uuid Version ~3.0