Download the PHP package flobbos/laravel-crudable without Composer

Laravel-Crudable

If you want to save time on your crud operations

This Laravel package is for saving time on CRUD operations when used in combination with Repositories or Services. The trait covers the basics needed for running simple CRUD operations. It also comes with a Contract that you can bind to your services via automated contextual binding.

Docs

• Installation
• Configuration
• Generators
• Translations
• Slugs
• Usage
• Functions
• Exceptions
• Laravel compatibility

Installation

Install package

Add the package in your composer.json by executing the command.

Next, if you plan on using the Contract with automated binding, add the service provider to app/config/app.php

Configuration

Publish configuration file

Laravel 5.*

Auto binding

Auto binding is used to run through the implementation list explained below. If this is set to true the auto binding feature will be used.

Namespace for services

Here you can set your default namespace for your service or repository classes.

Namespace for resource controllers

If you wish to set a default namespace for resource controllers use this option. Which will be used when in silent mode in the resource generator.

Select CSS Framework

Since Laravel 8 switched to Tailwind CSS there are two options of views that can be generated. Just set the config to bootstrap or tailwind, depending on what you need.

Implementations

Update the configuration according to your needs. A sample configuration is provided in the config file.

Fixed bindings

If you are using your own contracts you may want to use fixed bindings instead of the contextual binding mentioned above. This automatically binds your implementation to your specifically designed contract.

Generators

Service Generator

You can generate your own service/repository classes that implement the model and already use the Crudable trait. So easy.

The above command will generate a service class in App\Services (depending on your configuration setting mentioned above) that looks like this:

Adding the option --contract will load up the service class with a custom contract named after the provided service class.

Controller Generator

You can generate either a blank controller or a complete resource controller.

This will generate the resource controllers with all necessary basic functions already filled in for you based on the Crudable functionality.

This of course only covers the very basic functions but saves you from writing the same boiler plate code over and over again.

If you just need a blank controller with just the services implemented use the blank option like so:

Adding the option --contract will put a custom contract into the controller named after the controller class name provided.

View Generator

You can generate basic views for create/edit/index based on the Bootstrap version that shipped with Laravel.

The above command will generate a basic listing template, the form template for creating a new resource and of course the form template for editing. It is assumed that your views live inside an "admin" folder in resources/views.

Resource Generator

If you're starting out fresh you may wish to generate the entire resource including the model, service, resource controller and views.

All necessary suffixes (Controller, Service) will be added automatically. The generator will ask you which parts to create. If you just want to generate everything without interruptions use silent mode:

You can also use the --contract option for a custom contract version.

Contract Generator

If you want to use your own custom contract in combination with Crudable you can simply generate a boiler plate version.

This command will put a contract into your App\Contracts folder with the following content:

Translations

Translation info

Handling translations is based on my other package Laravel Translatable-DB, where the translations live in a separate table and are identified by either a language ID or a language code.

Basic options for translations

If you plan on using these functions for handling translations there are some basics you need to set in your service class:

If you add the --translated option when generating a resource the package will automatically generate a model translation class.

How to use translation functions

You need to run your language options as a foreach loop and send the translated data as an array like so (example is based on Bootstrap):

The hidden input is used to setup the correct relation to the corresponding language.

Data is then handled in a two step process. First the translation data is filtered and packaged into an array with this function:

This function returns an array that is then put into the save function:

In the edit function you also need to reference the translation ID used to identify an existing translation:

This way you can update existing translations and create new ones where necessary.

Available functions for handling translations

The following functions are available:

This function will take the translations from an input array and process them into a usable array of data that you can attach to a model.

You need to provide an array of translation data (\$translations), the translation key name and the language key name;

This function attaches the previously processed translations to an existing model.

This function updates translations and creates new ones if a translation isn't already present with the current model.

You have the option to set required fields within your repository/service via using \$this->required_trans so you always get the minimum translation data.

Here you can simply filter out all fields that were left blank in the form if you don't have required minimum fields mentioned above.

Slugs

Handle slugs with ease

If you want a service class to handle slugs for you automatically, all you need to do is set the following variable to the field you would like to be transformed into a slug:

Also implement the Sluggable interface like so:

Creating slugs

In the example scenario the field 'title' will be transformed into a URL slug and saved to the default 'slug' field in the database.

If you wish to name the slug field differently you need to set the following variable to the field name you prefer:

Retrieving resources with slugs

Of course you need to be able to retrieve database resources from their respective tranlated slugs. No worries, we already thought of that. Use the interface and trait:

This will give you access to the following functions:

With this function you can retrieve the requested resource ID from the given translated URL slug.

If you need to get the URL slug of a specific resource in a specific language just use this function.

The same functions also exist for non translated slugs. Just in case.

Usage

Repository/Service implementation

Add the package to the repository or service where you want the trait to be used.

By injecting the model into the service or repository and assigning it to the protected \$this->model, the trait now has access to your model and can work its magic.

Auto binding explained

You have the option to use auto binding in the config which automatically binds the Crud contract to your implementation.

The ServiceProvider automatically binds the Crud interface to the implementation you specified in the config as explained below.

Use your own contracts

By simply extending the Crud contract you can define your own logic without needing to redeclare everything that Crudable already provides.

Functions

get

This will perform a simple get call on the model resource. You can optionally pass an ID to the function and it will do the same thing as find.

find

This will get the resource with the given ID.

first

First will get you the very first row from from your resource, it works the same as the original Laravel version pretty much with the added Crudable benefits.

Where

The where function accepts parameters and passes them along to the Eloquent where method. It returns \$this so you can chain it onto other methods.

setRelation

The setRelation method acts like the with() statement you are used to from Eloquent. Just pass in an array of eager loading statements complete with callbacks an everything else. Can also be chained.

with

This works just like setRelation but you can either pass a string OR an array.

orderBy

This method just passes along your orderBy statement to Eloquent.

withHasMany

The method adds hasMany data to your create statement.

withBelongsToMany

With this method you can automatically save related data in a many-to-many relationship. Just pass an array of the data to be synced and the relation name from your model as the second parameter.

delete

Delete will remove a model from the database, unless soft deletes are in use. If you want to permanently delete a model you need to give it true as the second parameter.

restore

The restore function simply recovers a previously soft deleted model.

handleUpload

Processing uploads is somewhat cumbersome so I thought I'd include an easy to use function for handling single file image uploads. You just pass in the request object, the fieldname for the photo upload, the folder where the photo is supposed to go, the storage disk and you can optionally have the photo name randomized by that function so files don't get overwritten. Defaults are below.

Exceptions

MissingRelationData

This is thrown if your trying to save a hasMany or belongsToMany relationship with empty data.

MissingRequiredFields

This exception occurs when you're trying to call required_trans without setting the necessary data for it.

MissingTranslations

This exception is thrown in the case that no translations are present because all fields were empty or the required fields weren't filled out.

MissingSlugField

This exception is thrown when you forgot to define your slug field in the service class.

SlugNotFound

The SlugNotFoundException is thrown when you're trying to get a resource ID from a normal or a translated slug.

Laravel compatibility

Notice: If you're planning on using automated binding in Laravel <5.3 you need to update the config file to reflect the correct usage. Please refer to the Laravel documentation.

Have fun CRUDding! :-)