README.md

Laravel Core Package

Core: Additional core functionalities for Laravel including the Localisation: C3P0 for Laravel. Take a look at contributing.md to see a to do list.

Installation

Via Composer run the following:

# Install the package.
$ composer require pwweb/laravel-core

# Publish config, migration, languages and controllers.
$ php artisan vendor:publish --provider="PWWEB\Core\CoreServiceProvider"

# Run migrations
$ php artisan migrate

Pre-requisites

The package assumes a standard Laravel installation if the bundled default controllers for the entities are to be used. The bundled controllers extend from App\Http\Controllers\Controller. If other, custom base controllers are used as part of the installation, refer to Customising.

Configuration

Customising

The package provides the following tags for publishing individual components for customising:

Tag	Description
pwweb.core.config	Publish the configuration files to e.g. adjust database table names.
pwweb.core.migrations	Publish the migration file(s) to make alterations to the database tables.
pwweb.core.language	Publish the language files to make adjustments to the translation strings.
pwweb.core.views	Publish the view files to make adjustments to the overall structure of the views.

Extending Models

Models can be extended to include additional functionalities or add relationships to other models. When doing so, the configuration for this package needs to be exported and the class names need to be adjusted accordingly.

<?php

return [
    'models' => [
        'user' => Namespace\Of\My\User::class,
        ...
    ]
];

Default and Fallback Language

It is recommended to change your app.php to use both the ISO-639-1 ISO Language Code as well as the ISO-3166 ISO Country Code. This can be achieved by changing the following two variables:

<?php

return [
    ...
    'locale' => 'en-GB',
    'fallback_locale' => 'en-GB',
    ...
];

3rd Party Dependencies

This package relies on a few other packages. You should review their documentation as well:

• spatie/laravel-medialibrary
• spatie/laravel-permission

Usage

Users and Persons

In order to use the user and person model, rather than the default user model provided out of Laravel, the auth.php configuration file needs to be modified to the following:

<?php
'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => \PWWEB\Core\Models\User::class,
    ],
],

Using Laravel Auth

If the default laravel authentication is used and the controllers have been published, some changes are necessary to the RegisterController.php.

<?php
// Add the following lines.
use PWWEB\Core\Models\User;
use PWWEB\Core\Models\Person;

// Change the following two functions.
protected function validator(array $data)
{
    return Validator::make(
        $data,
        [
            'name' => ['required', 'string', 'max:255'],
            'surname' => ['required', 'string', 'max:255'],
            'email' => ['required', 'string', 'email', 'max:255', 'unique:'.User::getTableName()],
            'password' => ['required', 'string', 'min:8', 'confirmed'],
        ]
    );
}

protected function create(array $data)
{
    $person = Person::create(
        [
            'name' => $data['name'],
            'surname' => $data['surname'],
        ]
    );

    $user = new User(
        [
            'email' => $data['email'],
            'password' => Hash::make($data['password']),
        ]
    );
    $user->person()->associate($person);
    $user->save();

    $user->assignRole('user');

    return $user;
}

Addresses

The package provides a trait HasAddresses which can be used to allow models to be associated with addresses.

<?php

namespace Path\To;

use Illuminate\Database\Eloquent\Model;
use PWWEB\Core\Traits\HasAddresses;

class MyModel extends Model
{
    use HasAddresses;
}

Language Switcher

The localisation package provides a language switcher that can easily be added to blade templates as follows (note: the <div> is exemplary):

...
<div class="anyContainer">
    {{ Localisation::languageSelector() }}
</div>
...

GraphQL

The package provides a graphql.schema file for use within your parent project. This can be included in your primary schema file as follows:

#import ../vendor/pwweb/laravel-core/graphql/schema.graphql

Note: don't forget to update the vendor path should yours be in a different location, relative to your primary schema file.

Blade Directives

@date

The date directive allows for the display and formatting of dates using Carbon\Carbon. In case no date is supplied (i.e. null), no error is thrown and an empty string returned. If no format is supplied, the default format from configuration is used.

<?php
@date(Carbon\Carbon $date, string $format)

@menu

˜ The menu directive allows for the display of a menu based on the environment and root node provided.

<?php
@menu(string $environmentSlug, string $rootNodeSlug)

Exchange Rates

The package has an exchange_rates table that can be used to hold the historic exchange rates. To automatically update the table, a Queueable Job has been provided. This can be used with Laravel's Task Scheduling to update on a regular basis.

<?php
use PWWEB\Core\Jobs\UpdateExchangeRates;
//...
$schedule->job(new UpdateExchangeRates, 'target_queue')->timezone('Europe/Paris')->dailyAt('16:30');
//...

N.B.: The rates are taken from the European Central Bank and they update their rates daily at about 16:00 CET. Therefore you should ensure that the task is run shortly after to get the latest rates.

If you want to see the original content of the file you can find it here.

FAQs

During install via composer you get the following messages:

 ErrorException  : Trying to access array offset on value of type null

  at /var/www/vendor/pwweb/core/src/CoreServiceProvider.php:107
    103|     protected function registerModelBindings()
    104|     {
    105|         $config = $this->app->config['core.models'];
    106|
  > 107|         $this->app->bind(CountryContract::class, $config['country']);
    108|         $this->app->bind(LanguageContract::class, $config['language']);
    109|         $this->app->bind(CurrencyContract::class, $config['currency']);
    110|     }
    111|

  Exception trace:

  1   Illuminate\Foundation\Bootstrap\HandleExceptions::handleError("Trying to access array offset on value of type null", "/var/www/vendor/pwweb/core/src/CoreServiceProvider.php", [])
      /var/www/vendor/pwweb/core/src/CoreServiceProvider.php:107

  2   PWWeb\Localisation\CoreServiceProvider::registerModelBindings()
      /var/www/vendor/pwweb/core/src/CoreServiceProvider.php:81

  Please use the argument -v to see more details.

This is due to the command php artisan config:cache has been run. We suggest you delete the cache file bootstrap/cache/config.php and then run composer dump-autoload to be sure.

Change log

Please see the changelog for more information on what has changed recently.

Contributing

Please see contributing.md for details and a todo list.

Security

If you discover any security related issues, please use the issue tracker.

Credits

• PW*Websolutions
• All Contributors

License

Copyright © pw-websolutions.com. Please see the license file for more information.