Custom Laravel

customlaravel.com by @stauffermatt

View Slide

Before we start... !

View Slide


View Slide

One more thing...

View Slide

A brief history of my talks.

View Slide

Why Modern PHP Is Amazing And
How You Can Use It Today
PeersConf 2014

View Slide

Sharing Laravel
Laracon Eu 2014

View Slide

Leveraging Laravel
Laracon US 2015

View Slide

Empathy Gives You Superpowers
Laracon Eu 2015

View Slide

Mastering the
Illuminate Container
Laracon Online 2017

View Slide

Custom Laravel
Laracon US 2017

View Slide

Wherefore
"Custom Laravel"?

View Slide

PART I
The soul of customization

View Slide

Laravel:
We've got the
best defaults

View Slide

Laravel:
Convention over
configuration

View Slide

Laravel:
Convention and over
(when helpful) configuration

View Slide

Customizing Laravel: the basics
▸ Built-to-be-modified base code (/app/*)
▸ The most flexible container you've ever seen, and Illuminate Contracts
▸ Macros, façades, re-binding, and more
▸ Environment variables and conditional config
▸ It's Just PHP™

View Slide

What you choose to
customize matters.

View Slide

“Taking it too far is a rite of passage”
- Jeffrey Way

View Slide

TwentyPercent.fm
!
macros... ?
(an anecdote)

View Slide

One of the
hardest things to discover
in any new app is:
"where/how is this happening?"

View Slide

Prioritize
Discoverability

View Slide

Write your apps so
anyone who has read the
Laravel docs can jump
into them easily

View Slide

LARAVELUPANDRUNNING.COM
buy

View Slide

Write your apps so
anyone who has read the
Laravel docs can jump
into them easily

View Slide

The opposite of discoverability is...
! CUSTOMIZATION DEBT !

View Slide


View Slide

Discoverability caveat
Just because something is less discoverable
doesn't mean it's bad.
Sometimes the best tool isn't the most discoverable.
Sometimes it's us that needs to change, not the tool.

View Slide

Discoverability Disasters
▸ Overriding default methods like create()
▸ Modifying the request object
▸ Route::controller
▸ Custom façades that aren't façades
▸ Anything makes you go "that's so clever" instead of "that's so simple"

View Slide


View Slide

Tag::create(request()->all());

View Slide

How to
customize Laravel,
and how to do it
responsibly

View Slide

PART II
Customization
tips & tricks

View Slide


View Slide

Preface:
the container and service providers

View Slide

The container in 5 minutes
▸ registering things into it
▸ resolving things out of it
▸ things Laravel resolves using it
▸ autowiring vs. explicit
▸ service providers
▸ aliases and Facades

View Slide

Registering things into the container
▸ Key value store: put this thing at this address
▸ "Address": a string, usually a fully-qualified class name or a shortcut
string like "logger"
▸ "Thing": usually either a class name, a Closure, or an object
app()->bind('address', Thing::class);
app()->bind('logger', Logger::class);

View Slide

Resolving things out of the container
▸ Ask for the "thing" at the given "address"
▸ "give me the thing for address 'logger'"
▸ app()->make('logger') returns an instance of Logger
▸ Also can resolve by type hinting a container-resolved class like a
Controller

View Slide

Things Laravel resolves using the container
▸ Anything Laravel creates itself it creates using the container
▸ Controllers, middleware, etc.
▸ Why we can type hint dependencies in a controller
▸ Also some methods; controller methods, firing jobs, etc.
class MyController {
public function __construct(APIClient $client) {

View Slide

Autowiring vs. explicit binding
▸ The container knows how by default; ask for "App\Thing" and it tries
new App\Thing
▸ If App\Thing has dependencies it'll do the same for each
▸ If all dependencies are easy to resolve then you're good! If not..
▸ app()->bind(Thing::class, function () {
return new App\Thing('my-api-code'); });

View Slide

Aliases and Facades
▸ You can "alias" one address to another:
app()->alias('logger', SomeOtherLogger::class)
▸ "When I ask for SomeOtherLogger, give me 'logger'"
▸ Façades say "make a new class; let me call statics on it and proxy them
through to an instance of another class"

View Slide


View Slide

Back to the show

View Slide

Custom
Laravel
101

View Slide

Config
▸ Make custom config file keys (services.mailchimp.key)
▸ Make custom config files (config/chat.php)
▸ Make up your own .env variables and import into your config
▸ Important: Don't directly reference env() inline!

View Slide

Default controllers
▸ Default auth controllers provide customization hooks:
▸ Customize views; e.g. auth.passwords.email
▸ Customize return routes; e.g.
LoginController@$redirectTo
▸ Override protected methods; e.g. validateEmail(),
sendResetLinkResponse(), validateLogin()

View Slide

Default controllers (cont)
▸ Override intended "hook" methods; e.g.
LoginController@authenticated(),
LoginController@username()
▸ Some are placed in your default controller
(RegisterController@create) but all are adjustable

View Slide

Default providers
▸ AppServiceProvider ! a.k.a. core hacking for newbs
class AppServiceProvider extends ServiceProvider
{
public function boot() {
//
}
public function register() {
//
}

View Slide

Default providers (cont)
▸ AuthServiceProvider@boot and
EventServiceProvider@boot
class AuthServiceProvider extends ServiceProvider
{
protected $policies = [
'App\Model' => 'App\Policies\ModelPolicy',
];
public function boot() {
$this->registerPolicies();
//
}

View Slide

Default providers (cont)
▸ RouteServiceProvider@boot, @map !
class RouteServiceProvider extends ServiceProvider
{
public function boot()
{
//
parent::boot();
}
public function map()
{
$this->mapApiRoutes();
$this->mapWebRoutes();
//
}
protected function mapWebRoutes()
{
Route::middleware('web')
->namespace($this->namespace)
->group(base_path('routes/web.php'));
}

View Slide

Pro tip
Any time the stock files have //,
that's a sign you should consider customizing there.
class AuthServiceProvider extends ServiceProvider
{
public function boot()
{
$this->registerPolicies();
//
}

View Slide

Default middleware
▸ EncryptCookies@except, TrimStrings@except,
VerifyCsrfTokens@except
▸ RedirectIfAuthenticated: redirect('/home')
class EncryptCookies or TrimStrings or VerifyCsrfTokens
{
protected $except = [
//
];

View Slide

Custom middleware groups
▸ api and web out of the box
▸ Add more in App\Http\Kernel@$middlewareGroups

View Slide

Custom middleware groups (cont)
class Kernel extends HttpKernel
{
protected $middlewareGroups = [
'web' => [
\App\Http\Middleware\EncryptCookies::class,
// ...
],
'api' => [
'throttle:60,1',
'bindings',
],
'admin' [
'web',
'some-other-awesome-middleware',
]
];

View Slide

Custom middleware
▸ Make your own: watch for "guards", etc. in your controller methods
▸ php artisan make:middleware
KeepOutBadPeople
▸ Apply globally, add to a custom middleware group, make route optional

View Slide

Custom middleware (cont)
class KeepOutBadPeople
{
public function handle($request, Closure $next)
{
if ($this->isBad($request->person)) {
abort(404);
}
return $next($request);
}

View Slide

Exceptions
▸ Custom exceptions (e.g.
TryingToHackUsWhatTheHeckException)
▸ Custom global exception handling rules

View Slide

Exceptions (cont)
Customize exception handling: Pre-5.5
App\Exceptions\Handler@report;
check for instance type and respond
Customize exception handling: 5.5+
Define how to report an exception on the exception; @report()

View Slide

Includes
▸ Extract chunks of code to includes
▸ See: routes/web.php from before; also console.php
▸ What about schedule.php?

View Slide

Includes (cont)
// From this:
protected function schedule(Schedule $schedule) {
// $schedule->command('inspire')
// ->hourly();
}
// To this:
protected function schedule(Schedule $schedule) {
require base_path('schedule.php');
}

View Slide

Frontend
▸ php artisan make:auth
▸ 5.5 Frontend presets
▸ Default files are just that; defaults!

View Slide

GIF BREAK

View Slide


View Slide

Custom
Laravel
201

View Slide

Tests
▸ Add assertions to the base test class;
e.g. assertUserIsAdmin
▸ Re-bind/mock classes, migrate/seed in setUp
▸ Custom variables in phpunit.xml
▸ Test-specific .env.testing
▸ RefreshDatabase migration trait, coming in 5.5

View Slide

Helpers
▸ Bring back helpers.php!
▸ What works for your domain? sync(), etc.
{
"autoload": {
"files": ["helpers.php"]
}
}

View Slide

Advanced container binding/re-binding
▸ Get familiar with app()->bind() and its cousins
▸ Step 1. Bind your own class
app()->bind(MyClass::class, Closure)
▸ Step 2. Bind your class to interfaces
app()->bind(MyInterface::class,
ClosureOrClassName)

View Slide

Advanced container binding/re-binding (cont)
▸ Step 3. Bind your class to a global shortcut
app()->bind('myalias', ClosureOrClassName)
▸ Step 4. Re-bind other classes/interfaces to that global shortcut
app()->alias('myalias',
SomeContractClassName)

View Slide

An example
class MyContainer extends Container
{
public function storagePath()
{
return $this->basePath . '/storageOMGyay';
}
}

View Slide

Advanced container binding/re-binding (cont)
Example from Bugsnag docs:
$this->app->singleton('bugsnag.logger', function (Container $app) {
return new LaravelLogger($app['bugsnag']);
});
$this->app->singleton('bugsnag.multi', function (Container $app) {
return new MultiLogger([$app['log'], $app['bugsnag.logger']]);
});
Bind:
$this->app->alias('bugsnag.logger', \Illuminate\Contracts\Logging\Log::class);
$this->app->alias('bugsnag.logger', \Psr\Log\LoggerInterface::class);

View Slide

Contracts
Interfaces to all major Laravel components
Illuminate\Contracts\*
namespace Illuminate\Contracts\Logging;
interface Log
{
public function alert($message, array $context = []);
public function critical($message, array $context = []);
// ...

View Slide

Breathe

View Slide

Packages & Publishing
▸ Packages often allow you to "publish" config and view files
▸ E.g. customize Spark views or Media-Library config by running:
▸ php artisan vendor:publish
▸ Note: 5.5 vendor:publish = !

View Slide

Custom Façades
Step 1. Create the Façade class extending
Illuminate\Support\Facades\Facade
Step 2. Implement getFacadeAccessor() method; return a string
that would resolve out of the container
Step 3. Register it in config/app.php@aliases

View Slide

Façade example
// FitbitServiceProvider.php
public function register() {
$this->app->singleton('fitbit', function () { ... });
}
// Somewhere
class Fitbit extends Illuminate\Support\Facades\Facade {
public function getFacadeAccessor() { return 'fitbit'; }
}
// In consuming code (controller, etc.)
Fitbit::nonStaticMethodOnFitbitClass();

View Slide

Swapping Façades and bindings in tests
▸ Swappable façades e.g.:
Cache::shouldReceive('get')->once()->with('key')-
>andReturn('value')
▸ Shout out to MailThief ❤
▸ Swap `em yourself!

View Slide

Custom validation: pre-5.5
// In a service provider:
Validator::extend('repo', function ($attribute, $value, $parameters, $validator) {
return app(Client::class)->validRepository($url);
});
// or
Validator::extend('repo', 'RepoValidator@validate');
// .. in your language file:
[
"repo" => "The given repository is invalid.",
]

View Slide

Custom validation: 5.5+
class ValidRepository implements Rule
{
public function __construct($source, $branch)
{
$this->source = $source;
$this->branch = $branch;
}
public function passes($attribute, $value)
{
if (! $this->source instanceof Source) return false;
return $this->source->client()->validRepository(
$value, $this->branch
);
}
public function message()
{
return 'The given repository is invalid.';
}

View Slide

Macros
// In a service provider
Response::macro('jsend', function ($body, $status = 'success') {
if ($status == 'error') {
return Response::json(['status' => $status, 'message' => $body]);
}
return Response::json(['status' => $status, 'data' => $body]);
});
// In a route
return response()->jsend(Order::all());

View Slide

Blade directives: traditional style
Blade::directive('public', function () {
return "isPublic()): ?>";
});
Blade::directive('endpublic', function () {
return "";
});
// Use:
@public
Only show on the public web site
@endpublic

View Slide

Blade directives: using Blade::if in 5.5
Blade::if('env', function ($env) {
return app()->environment($env);
});
@env('production')

@endenv

View Slide

View Composers
// Class-based composer
View::composer(
'minigraph', 'App\Http\ViewComposers\GraphsComposer'
);
// Closure-based composer
View::composer('minigraph', function ($view) {
return app('reports')->graph()->mini();
});

View Slide

Custom route model bindings
Route::bind('user', function ($value) {
return App\User::public()
->where('name', $value)
->first();
});
// In your binding
Route::get('profile/{user}', function (App\User $user) {
//
});

View Slide

Form requests
// Traditional request injection
public function index(Request $request) {}
// Form Request Validation
public function store(StoreCommentRequest $request) {}
// Form Request
class StoreCommentRequest extends FormRequest {
public function authorize() { return (bool)rand(0,1); }
public function rules () { return ['validation rules here']; }
}

View Slide

Form requests (cont)
class StoreCommentRequest extends FormRequest
{
public function sanitized()
{
return array_merge($this->all(), [
'body' => $this->sanitizeBody($this->input('body'))
]);
}
protected function sanitizeBody($body)
{
// Do stuff
return $body;
}
}

View Slide

GIF BREAK

View Slide


View Slide

Custom
Laravel
301

View Slide

Arbitrary route bindings
Route::bind('topic', function ($value) {
return array_get([
'automotive' => 'I love cars!',
'pets' => 'I love pets!',
'fashion' => 'I love clothes!'
], $value, 'undefined');
});
// In your routes file
Route::get('list/{topic}', function ($topic) {
//
});

View Slide

Arbitrary route bindings (cont)
Route::bind('repository', function ($value) {
return app('github')->findRepository($value);
});
// In your routes file
Route::get('repositories/{repository}', function ($repo) {
//
});

View Slide

Custom request objects
class MyMagicalRequest extends Request
{
// Add methods, properties, etc.
}
// Type-hint in a route
public function index(MyMagicalRequest $request) {}
// Or even re-bind globally in public/index.php
$response = $kernel->handle(
// $request = Illuminate\Http\Request::capture()
$request = App\MyMagicalRequest::capture()
);
// (but, remember, macros!)

View Slide

Custom response objects
class MyMagicalResponse extends Response
{
// Add methods, properties, etc.
}
// Return from a route
public function index()
{
return MyMagicalResponse::forUser(User::find(1337));
}
// Or macro it
Response::macro('magical', function ($user) {
return MyMagicalResponse::forUser($user);
});
return response()->magical($user);

View Slide

Custom response objects: Responsable in 5.5
class Thing implements Responsable
{
public function toResponse()
{
return 'HEY THIS IS A USER RESPONSE FOR THING NUMBER ' . $this->id;
}
}

View Slide

Custom Eloquent collections
class ItemCollection extends Collection
{
public function price()
{
return $this->sum('amount') + $this->sumTax();
}
public function sumTax()
{
return $this->reduce(function ($carry, $item) {
return $carry + $item->tax();
}, 0);
}
}
class Item
{
public function newCollection(array $models = [])
{
return new ItemCollection($models);
}

View Slide

Hijacking index.php
if ($response->getStatusCode() != 404) {
$response->send();
$kernel->terminate($request, $response);
exit;
}
// CodeIgniter or whatever else

View Slide

GIF BREAK

View Slide


View Slide

Independent Study
(other tools)

View Slide

Custom Homestead config
composer require laravel/homestead --dev
php vendor/bin/homestead make
# generates Homestead.yaml:
ip: 192.168.10.10
memory: 2048
cpus: 1
provider: virtualbox
authorize: ~/.ssh/id_rsa.pub
keys:
- ~/.ssh/id_rsa
folders:
-
map: /Users/mattstauffer/Sites/live-from-new-york-its-me
to: /home/vagrant/Code/live-from-new-york-its-me
sites:
-
map: live-from-new-york-its-me
to: /home/vagrant/Code/live-from-new-york-its-me/public
databases:
- homestead
name: live-from-new-york-its-me
hostname: live-from-new-york-its-me

View Slide

Lambo pro tip
▸ Lambo with config and after scripts ❤"

View Slide

Commonly installed packages
https://mattstauffer.co/blog/what-packages-do-you-install-on-every-
laravel-application-you-create

View Slide

Recap
1. With great power... customize responsibly!
2. Prioritize, but don't enshrine, discoverability
3. 101: Modify the intended-to-be-modified; make your own, too
4. 201: Use the container!
5. 301: Override/custom all the classes!
6. Custom Homestead, Lambo

View Slide

customlaravel.com
(for tips and slides)

View Slide

Custom Laravel

Custom Laravel

Matt Stauffer

More Decks by Matt Stauffer

Other Decks in Technology

Featured

Transcript