README

Controllers for common UI and endpoints in Laravel,
like API authentication, password change, login page, etc.

Laravel 9.x/10.x

Install the saritasa/laravel-controllers package:

$ composer require saritasa/laravel-controllers  

Available controllers

There are 2 types of controllers:

• Web - interactive UI for user - traditional Laravel controllers.
  Many of them just provide out-of-the-box Laravel functionality,
  using built-in traits.
• Api - for programmatic integration with 3d party applications,
  like mobile apps (iOS, Android) or single-page HTML applications,
  built on modern frontend frameworks - React.JS, AngularJS, VueJs, etc.
  API utilizes Dingo/Api library
  and custom extensions for it: saritasa/dingo-api-custom

Controllers, described below, exist, but you must register routes for them manually

Methods

• function json($data, IDataTransformer $transformer = null): Response

Example:

class UserApiController extends BaseApiController
{    
  public function __construct(UserTransformer $userTransformer)
  {      
    parent::__construct($userTransformer);  
  }

  public function editUserProfile(Request $request, User $user): Response  
  {
    $this->validate($request, $user->getRuels());
    $user->fill($request->all());
    $user->save();
    return $this->json($user);
  }
}

JWTAuthApiController Authenticate API Controller. Uses JWT authentication

Utilizes Dingo\Api JWT Auth
settings and underlying tymon\jwt-auth

Example: routes\api.php:

app('api.router')->version(config('api.version'), ['namespace' => 'Saritasa\Laravel\Controllers\Api'],    
  function (\Dingo\Api\Routing\Router $api) {  
    // Authentication $api->post('auth', 'AuthController@login');   // Login $api->put('auth', 'AuthController@refreshToken'); // Refresh expired token                
    $api->delete('auth', 'AuthController@logout')->middleware('api.auth'); // Logout  
  });

Customize login request

In some case, we're using email field for login with email or username in application. So, the email field should validation by required and string rule. Or you want to use username instead of email.

How to bind ILoginRequest with custom request class

<?php

namespace App\Providers;

use App\Http\Requests\Auth\LoginRequest;
use Illuminate\Support\Facades\URL;
use Illuminate\Support\ServiceProvider;
use Saritasa\LaravelControllers\Requests\Concerns\ILoginRequest;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        $this->app->bind(ILoginRequest::class, LoginRequest::class);
    }
}

<?php

namespace App\Http\Requests\Auth;

use Illuminate\Foundation\Http\FormRequest;
use Saritasa\LaravelControllers\Requests\Concerns\ILoginRequest;

class LoginRequest extends FormRequest implements ILoginRequest
{
    /**
     * @inheritDoc
     */
    public function rules(): array
    {
        return [
            'username' => 'required|string',
            'password' => 'required|string',
        ];
    }
}

ForgotPasswordApiController, ResetPasswordApiController These controllers are responsible for handling password reset emails.

Utilize native Laravel password management without UI, in JSON API.

Example: routes\api.php:

app('api.router')->version(config('api.version'), ['namespace' => 'Saritasa\Laravel\Controllers\Api'],
  function (\Dingo\Api\Routing\Router $api) {
    $api->post('auth/password/reset', 'ForgotPasswordApiController@sendResetLinkEmail');
    $api->put('auth/password/reset', 'ResetPasswordApiController@reset');
  });

Contributing

1. Create fork, checkout it
2. Develop locally as usual. Code must follow PSR-1, PSR-2 -
   run PHP_CodeSniffer to ensure, that code follows style guides
3. Cover added functionality with unit tests and run PHPUnit to make sure, that all tests pass
4. Update README.md to describe new or changed functionality
5. Add changes description to CHANGES.md file. Use Semantic Versioning convention to determine next version number.
6. When ready, create pull request

Make shortcuts

If you have GNU Make installed, you can use following shortcuts:

• make cs (instead of php vendor/bin/phpcs) -
  run static code analysis with PHP_CodeSniffer
  to check code style
• make csfix (instead of php vendor/bin/phpcbf) -
  fix code style violations with PHP_CodeSniffer
  automatically, where possible (ex. PSR-2 code formatting violations)
• make test (instead of php vendor/bin/phpunit) -
  run tests with PHPUnit
• make install - instead of composer install * make all or just make without parameters -
  invokes described above install, cs, test tasks sequentially -
  project will be assembled, checked with linter and tested with one single command

Resources

• Bug Tracker
• Code
• Changes History
• Authors