Forem: ryan

3 Ways to Keep Your Laravel Routes Organized

ryan — Thu, 16 Jul 2020 19:54:44 +0000

Introduction

Laravel routing allows us to easily map a URI pattern to a particular controller, or method. It's easy to let routing get unorganized if we don't follow a pattern.

In this post, we'll go over a simple pattern that puts namespace, routing groups, and common HTTP operations into a single component.

Use route groups
Apply a name to the route group
Use a common namespace for all operations under the route group.

Before

use Illuminate\Support\Facades\Route;

Route::namespace('Site\Secrets')
    ->get('/sites/{site}/secrets', 'SecretController@get')
    ->name('site.secrets.index');

Route::namespace('Site\Secrets')
    ->get('/sites/{site}/secrets', 'SecretController@post')
    ->name('site.secrets.new');

Route::namespace('Site\Secrets')
    ->get('/sites/{site}/secrets', 'SecretController@delete')
    ->name('site.secrets.delete');

The above pattern is fine, but we're repeating ourselves A LOT. Just take a look at how many times we typed sites/{site}/secrets. There's a better way to make our route definitions easier to read, maintainable, and overall better.

After

use Illuminate\Support\Facades\Route;

Route::namespace('Site\Secrets')->name('site.secrets.')
    ->prefix('/sites/{site}/secrets')->group(function () {
        Route::get('/', 'SecretController@get')
            ->name('index');
        Route::post('/', 'SecretController@post')
            ->name('new');
        Route::delete('/{secret}', 'SecretController@delete')
            ->name('delete');
});

Notice how we're using Route Groups. This allows us to apply common settings to each Route:: call inside the group callback.

All routes defined in our group will use the fully qualified PHP namespace of Site\Secrets. Laravel will resolve the fully qualfied controller class name to \App\Http\Controllers\Site\SecretsController.

If we're not sure where \App\Http\Controllers comes from, then we can go to line 17 of the RouteServiceProvider.php file. In this file, Laravel defines the namespace to be applied to our controller routes.

This means, that every route defined in our callback will have site.secrets. prepended to its name. In effect, the
index route would actually be site.secrets.name

Conclusion

As software engineers, we should strive to write maintainable and easy-to-read code.

PHP Deployment Best Practices When Using Composer

ryan — Sun, 01 Mar 2020 05:43:47 +0000

Overview

Composer is the de-facto dependency manager for PHP applications which was initially released almost 8 years ago March 2012.

Using Composer in your PHP can be used to increase one’s code reusability and enable your project to easily integrate maintained PHP libraries from Packagist, the main PHP Composer repository. Today we’ll highlight a few deployment best practices.

Composer Can Get Slow

This post will focus on how to make composer faster and remove the need to install packages with a fresh composer install each time you deploy your application.

Magento is an example of a composer project requiring lots of memory. Can you imagine how much memory you’d need if you needed to do a composer install for each of your deployments? Composer may fail with an Out of Memory error which is described in this Stack Overflow post.

Although it’s easy to add packages to your project, here at Amezmo we take a conservative approach to adding a new project dependency for the following reasons.

Slows down the initial composer install
Each composer package increases the chances of new security issues

Best Practices

This one is a no-brainer. Audit our composer.json file and of course remove any package references that aren’t required.

The second one, which is the reason I made this post is to ensure you’re running composer with the following flags.

composer \
    --no-ansi \
    --no-interaction \
    --optimize-autoloader \
    --no-progress \
    --no-dev \
    --profile \
    install

This command is documented in Amezmo’s documentation on installing composer packages with deployment hooks. Let’s go through these flags one by one

--no-ansi

This flag disables ANSI output which means that colorful output will be disabled. Colorful output as in green and red font colors and background colors that are pleasing to the human eye. This is great for when we’re running composer manually, but for automated deployments, we don’t want to clutter our log files with strange characters.

--no-interaction

Again, in the context of automated deployments, we do not want a deployment to be stalled waiting for input. This flag prevents composer from asking for user input.

--optimize-autoloader

This flag tells Composer to automize the autoloader code that gets generated. The autoloader is what gets invoked when your entry point does require 'vendor/autoload.php';

--no-progress

Since progress reporting uses special terminal ANSI codes, we don’t want to report progress since it will clutter our log files. It’s completely unnecessary when doing non-interactive deployments and composer installs.

--no-dev

This one is vital. We never want to install our development packages onto our production servers. Things such as phpunit and other packages that should never make it to production are considered a “dev” package. They have a special entry in the composer.json file under the “require-dev” property.

--profile

This one is optional, but I always like to include it because it shows how much memory Composer uses to install an individual dependency.

How to Cache Composer Packages at Deployment Time

Now that we’ve got our production-grade composer install command defined, let’s go through a simple way of making Composer faster when it comes to deploying.

Step 1.
Create a global Composer vendor directory somewhere completely outside of your webroot, and of course not publicly accessible.

Note: Amezmo uses a root directory layout as illustrated below, so we’re going to use this in our bash commands below. You can of course replace these directories with your own and the desired outcome will be achieved.

/webroot
|----logs
|----vendor
|----storage
|----current -> /webroot/release/${TIMESTAMP}.${COMMIT_ID}
|----release
|-------${TIMESTAMP}.${COMMIT_ID}
|-------${TIMESTAMP}.${COMMIT_ID

/webroot/vendor is our global wide package directory from which a link will be created for each release.

Run the following command to create the linked vendor directory from your release directory, to the global vendor directory. You must do this each time you deploy, and BEFORE running composer install from your release directory.

ln -sT /webroot/vendor webroot/release/${TIMESTAMP}.${COMMIT_ID}/vendor

Note it’s vital to run the above command prior to running composer install from your release directory. Here are the steps in order:

The release directory should be created
Run Git to get your source code
Execute the above command,
Finally run composer install

Having done everything in the above order, your packages will be “cached” into the /webroot/vendor directory and you will not need to freshly intstall your packages each time you deploy your application.

Conclusion

Defined a Composer command that eliminates any non-essential functionality.
Highlighted a best-practice deployment pattern for caching Composer packages at deploy time

Our mission at Amezmo is to remove the friction in secure PHP hosting and deployment and provide the best possible platform for PHP developers like myself. If you liked this post, please support the platform by hosting your code with us.

How to Write a Laravel Facade With a Service Provider

ryan — Wed, 05 Feb 2020 16:52:02 +0000

Prior to me discovering how the Laravel internals work, I would define static methods for most of my services. It quickly gets difficult to manage, once you need to keep non static state for a service, or you want dynamic behavior that is determined at runtime.

At the end you'll have an Asset class that looks like this:

Asset::js();

You'll use this asset class to dynamically insert a hash of your asset files in order to cache bust your static files when you deploy.

In this post I’ll share how I defined my own Asset class facade that is registered to the Laravel container in a service provider. First, let’s take a minute to understand my original Asset class. It was your typical static class.

<?php

namespace App\Utils;

class Asset
{
    /**
     * Return the asset path for the Stripe integration
     *
     * @return string
     */
    public static function stripe()
    {
        if (env('APP_DEBUG', false)) {
            return env('CDN_ENDPOINT') . '/js/stripe.js?t=' . time();
        }

        return env('CDN_ENDPOINT') . '/js/stripe.'.AMEZMO_ASSET_VERSION_HASH.'.js';
    }
}

The motivation for creating a custom Asset class was to be able to call it from a view. Amezmo has an asset build pipeline that generates a 16 byte hash of the filename. This hash is then stored to be used as a URI segment for cache busting JavaScript and CSS files.

The problem with the static asset class however, is that you cannot use Laravel’s DI container to inject services, such as a configuration block, or anything else that you would need. So, for the new non static implementation.

I started off by following Laravel’s pattern of putting each provider in it’s own directory. Create a new directory under your app directory called Asset. I added AssetManagerInterface to best follow the SOLID principles. However, it isn’t necessary to always implement an interface for a simple service.

Implementing the Service Provider

The Laravel DI container is powerful. It’s especially useful for registering singelton classes, such as the Asset class or a connection Redis, for example. Lot’s of Laravel’s built-in providers are singeltons.

<?php

namespace App\Asset;

use Illuminate\Contracts\Foundation\Application;

use App\Asset\AssetManager;

class AssetServiceProvider extends \Illuminate\Support\ServiceProvider
{
    public function register()
    {
        $this->app->singleton('amezmo.asset', function (Application $app) {
            $config = $app->make('config')['app'];
            return new AssetManager($app->basePath(), $config['debug'], $config['cdn']);
        });
    }

    public function provides()
    {
        return ['amezmo.asset'];
    }
}

It’s worth noting that you do not have to register your services directly. Laravel is smart enough to construct an instance of your service. However, since I am passing in a non-reference type as the first argument, Laravel would not be able to, simply because primitive values have no context. Once we have the service provider register to the container, we’re ready to add it to our app/config/app.php configuration array

<?php

// Note this file is stripped down for example purposes

return [
    'providers' => [
     // Custom service providers are added here
         App\Asset\AssetServiceProvider::class
    ],
    /*
    |--------------------------------------------------------------------------
    | Class Aliases
    |--------------------------------------------------------------------------
    |
    | 02/12/2019 - Also note, that by using an Alias, one does not have to
    | use a using statement for the class
    |
    | For example, since Validator is in the alias list, you do not have to insert
    | a use Illuminate\Support\Facades\Validator statement, you can do a
    | use Validator. However, this is bad practice.
    |
    */

    'aliases' => [
         'Asset' => App\Asset\Asset::class,
    ]
]

The entry added to the aliases array is that the facade Asset can be invoked from a view. Now let’s take a look at AssetManager where the real logic, hiding behind the facade actually takes place I’ve added other methods in this class. Perhaps it might give you some inspiration in your own projects.

As you can see, the constructor defines it’s dependencies and we provide them in the AssetServiceProvider This is great for performance, because we will be able to store the configuration in memory, and not, for example, call env() many times, which may end up calling into getenv from the C standard library.

<?php

namespace App\Asset;

use App\Asset\AssetManagerInterface;

class AssetManager implements AssetManagerInterface
{
    /** @var string */
    private $webpackAssetHash;

    /**
     * The assest that were compiled via Amezmo's custom generator
     * @var string
     */
    private $amezmoAssetHash;

    /** @var bool */
    private $debug;

    /** @var string */
    private $cdn;

    public function __construct($basePath, $debug, $cdn)
    {
        $this->webpackAssetHash = file_get_contents($basePath . '/webpack-hash.txt');
        $this->amezmoAssetHash = AMEZMO_ASSET_VERSION_HASH;
        $this->debug = $debug;
        $this->cdn = $cdn;
    }

    /**
     * Return the versioned javascript asset
     *
     * @return string
     */
    public function js()
    {
        return $this->cdn . '/dist/app.'.$this->webpackAssetHash.'.js';
    }

    /**
     * Return a versioned compiled css file
     *
     * @return string
     */
    public function css()
    {
        return $this->cdn . '/dist/app.'.$this->webpackAssetHash.'.css';
    }

    /**
     * Return fully qualified asset URL, using the CDN_ENDPOINT
     *
     * @param string $assetPath
     * @return void
     */
    public function url($assetPath)
    {
        if ($assetPath[0] === '/') {
            $assetPath = substr($assetPath, 1);
        }

        // With debug, we will not insert the hash, but a timestamp in order to prevent the browser
        // from caching it
        if ($this->debug) {
            return $this->cdn . '/' . $assetPath . '?t=' . time();
        }

        /** @var \SplFileInfo $fileInfo **/
        $fileInfo = new \SplFileInfo($assetPath);

        if (in_array($fileInfo->getExtension(), ['js', 'css'])) {
            return $this->cdn . '/' . $this->versionedAsset($assetPath);
        }

        return $this->cdn . '/' . $assetPath;
    }

    /**
     * Return the asset path for the Stripe integration
     *
     * @return string
     */
    public function stripe()
    {
        if ($this->$debug) {
            return $this->cdn . '/js/stripe.js?t=' . time();
        }

        return $this->cdn . '/js/stripe.'.$this->amezmoAssetHash.'.js';
    }

    /**
     * This function splits the path name in order to insert an amezmo version hash between the filename
     * and the file extension
     *
     * x.js => x.$AMEZMO_VERSION.js
     *
     * @param string $asset
     * @return string
     */
    public function versionedAsset($asset)
    {
        $components = explode('.', $asset);
        $componentsCount = count($components);
        $buffer = '';

        foreach ($components as $index => $component) {
            if ($index === $componentsCount - 2) {
                if ($index != 0) {
                    $buffer .= '.';
                }
                $buffer .= $component . '.' . $this->amezmoAssetHash;
            } else {
                if ($index != 0) {
                    $buffer .= '.';
                }
                $buffer .= $component;
            }
        }

        return $buffer;
    }
}

The Asset facade is very simple. It defines one method called getFacadeAccessor with returns a string with the value we’ve returned from AssetServiceProvider::provides()

<?php

namespace App\Asset;

use Illuminate\Support\Facades\Facade;

class Asset extends Facade
{
    /**
     * Get the registered name of the component.
     *
     * @return string
     */
    protected static function getFacadeAccessor()
    {
        return 'amezmo.asset';
    }
}

Benefits of Service Provider pattern with Facades

Being able to mock your service properly
Not depending on any hard coded dependencies.
All your dependencies are defined in your constructor, so you can swap in specific implementations for your use specific use case. For example, if you need different behavior for the service in a production or development environment.

This blog post was originally posted on Amezmo where they make PHP hosting and deployment painless. If you liked this guide, check out our guide on deploying Laravel applications.

How To Validate GitHub Webhooks With Laravel and PHP

ryan — Tue, 28 Jan 2020 19:33:06 +0000

How To Validate GitHub Webhooks With Laravel and PHP

Introduction

GitHub webhooks are sent to your endpoint when events occur in a repository. This is a powerful extensiblity feature that provides the developer a platform for many use cases such as push notifications and automatically deploying code when a repository has new commits. As security aware developers, we should always validate our incoming webhooks against a known token.

In this post, I'll show how to properly validate webhooks from GitHub. When we're done, you can use this code to validate your own hooks.

At the end you'll have an API endpoint in the form of
https://example.com/api/webhooks/github/handle that's validated by a method with the following signature:

protected function validateGithubWebhook($known_token, Request $request);

Prerequisites

Before you begin this guide you'll need the following:

A repository on GitHub
A public server that can accept HTTP requests from GitHUb
Laravel application

If you don't have a public server available, then you can sign up for a trial at Amezmo and deploy your application in seconds without having to setup Nginx, or PHP.

Step 1 — Generate a Secret Token

First, let's open up a shell and generate a random token that we'll use for our GitHub webhook:

openssl rand -hex 32

With the above command executed, copy the value into your .env file replacing the with the result of your command.

GITHUB_WEBHOOK_SECRET=test

After you've wired up the .env file, be sure to define the configuration entry in config/app.php. Add the following entry to the array.

'github_webhook_secret' => env('GITHUB_WEBHOOK_SECRET'),

Step 2 - Define the API Route in Laravel

Finally, let's define our API endpoint in our Laravel application. This endpoint will be an API endpoint type that will not set a session cookie. Since this endpoint will not authenticated against a user session, we do not need to set a cookie in the HTTP response.

Open up routes/api.php and define a new route group

Route::namespace('Webhooks')->prefix('/webhooks')->group(function () {
    Route::post('/github/handle', 'GithubWebhookProcessor@handle');
});

We've defined a route group with the name Webhooks. This allows us to stay generic while providing a path
to extensibility in case we want to add other webhook providers in the future.

Step 3. Create a webhook on GitHub.

Using any repository that you have on GitHub, create a webhook from the repository settings page.

Our webhook will be a JSON payload with just the push event for now. Use the token we generated in the first step for the Secret. Replace example.com with your own domain.

Next, we'll define our folder and PHP file where we'll define our class to handle this route.

Step 4 — Compose the Webhook Class

Create the Webhooks folder under app/Https/Controllers. Under our new Webhooks folder, define our new class in GithubWebhookProcessor.php.

<?php

namespace App\Http\Controllers\Webhooks;

use Illuminate\Http\Request;
use Psr\Log\LoggerInterface;

class GithubWebhookProcessor
{
    /** @var \Psr\Log\LoggerInterface */
    private $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    /**
     * Validate an incoming github webhook
     *
     * @param string $known_token Our known token that we've defined
     * @param \Illuminate\Http\Request $request
     *
     * @throws \BadRequestHttpException, \UnauthorizedException
     * @return void
     */
    protected function validateGithubWebhook($known_token, Request $request)
    {
        if (($signature = $request->headers->get('X-Hub-Signature')) == null) {
            throw new BadRequestHttpException('Header not set');
        }

        $signature_parts = explode('=', $signature);

        if (count($signature_parts) != 2) {
            throw new BadRequestHttpException('signature has invalid format');
        }

        $known_signature = hash_hmac('sha1', $request->getContent(), $known_token);

        if (! hash_equals($known_signature, $signature_parts[1])) {
            throw new UnauthorizedException('Could not verify request signature ' . $signature_parts[1]);
        }
    }


    /**
     * Entry point to our webhook handler
     *
     * @param \Illuminate\Http\Request $request
     *
     * @return mixed
     */
    public function handle(Request $request)
    {
        $this->validateGithubWebhook(config('app.github_webhook_secret'), $request);

        $this->logger->info('Hello World. The GitHub webhook is validated');
        $this->logger->info($request->getContent());
    }
}

Step 4 — Test it

We've wired everything up on our end, now we can test our webhook by creating a new commit in the repository where we defined our webhook.

Conclusion

Link to this repository on GitHub

The best setting.json for PHP development with Visual Studio Code

ryan — Mon, 30 Dec 2019 02:24:21 +0000

Overview

PHP is a dynamic object-oriented language that brings the developer the power of OOP along with the flexibility of dynamic typing. Type annotations are supported in PHP which allows you the ability to define the runtime type of function parameters.

IDE’s can be used to increase one’s productivity since most of them have built-in auto-completion and other useful features such as “Go to definition”, and “Find all references”.
One popular IDE is PHPStorm, but today we will highlight which Visual Studio Code extensions transform Visual Studio Code into a full-fledged IDE alternative for PHP.

With great power, comes great responsibility, and because Visual Studio Code is a powerful text editor that brings an extremely powerful extensibility API, it’s easy to find yourself with a nonsensical settings.json file. At the end of this post, your visual studio code will have these productivity features:

Errors, warnings, and other introspection such as unused variables.
Code completion
Function/Method signature parameter hinting.
Go to definition
DotEnv syntax highlighting
Find all references
Documentation when hovering over methods
Path autocompletion, for string literal file paths.
PSR code sniffing emitting errors, and warnings in real time.
Automatic PHP DocBlocks.

These features will be implemented by installing these extensions:

TLDR; the full settings file is on GitHub.

Step 1.

The first thing we need to do is disable default PHP support. This can be accomplished with two configuration items in your .vscode/settings.json file. The snippets in this post are extracted from the full file.

{
 "php.validate.enable": false,
 "php.suggest.basic": false,
}

This will allow our extensions to be used to their fullest extent and prevent any functional collisions.

Step 2.

By default, the php-redis extension is not included in the default configuration. So that means you will not have auto-complete for the Redis class. Now, let’s configure optimal Intelephense settings. Quick tip, when you’re editing a setting.json file in vscode, you can see the default value for the configuration item by typing the colon character, : and then clicking the tooltip.

"intelephense.stubs": [
    "apache",
    "redis",
    "bcmath",
    "bz2",
    "calendar",
    "com_dotnet",
    "Core",
    "ctype",
    "curl",
    "date",
    "dba",
    "dom",
    "enchant",
    "exif",
    "fileinfo",
    "filter",
    "fpm",
    "ftp",
    "gd",
    "hash",
    "iconv",
    "imap",
    "interbase",
    "intl",
    "json",
    "ldap",
    "libxml",
    "mbstring",
    "mcrypt",
    "meta",
    "mssql",
    "mysqli",
    "oci8",
    "odbc",
    "openssl",
    "pcntl",
    "pcre",
    "PDO",
    "pdo_ibm",
    "pdo_mysql",
    "pdo_pgsql",
    "pdo_sqlite",
    "pgsql",
    "Phar",
    "posix",
    "pspell",
    "readline",
    "recode",
    "Reflection",
    "regex",
    "session",
    "shmop",
    "SimpleXML",
    "snmp",
    "soap",
    "sockets",
    "sodium",
    "SPL",
    "sqlite3",
    "standard",
    "superglobals",
    "sybase",
    "sysvmsg",
    "sysvsem",
    "sysvshm",
    "tidy",
    "tokenizer",
    "wddx",
    "xml",
    "xmlreader",
    "xmlrpc",
    "xmlwriter",
    "Zend OPcache",
    "zip",
    "zlib"
],
"intelephense.telemetry.enabled": false,
"intelephense.format.enable": true,
"intelephense.completion.triggerParameterHints": true,
"intelephense.completion.insertUseDeclaration": true,
"intelephense.completion.fullyQualifyGlobalConstantsAndFunctions": true,
"intelephense.trace.server": "messages",
"intelephense.files.exclude": [
    "**/.git/**",
    "**/.svn/**",
    "**/.hg/**",
    "**/CVS/**",
    "**/.DS_Store/**",
    "**/node_modules/**",
    "**/bower_components/**",
    "**/storage",
    "**/storage/**",
    "**/tests/**",
    "**/resources/views/**",
    "**/database/migrations/**",
    "**/storage/framework/views/**",
    "_ide_helper.php",
    "_ide_helper_models"
]

Step 3 PHP Code Sniffer settings

"phpcs.executablePath": "vendor/bin/phpcs",
"phpcs.enable": true,
"phpcs.autoConfigSearch": true,
"phpcs.standard": "./phpcs.xml",
"phpcs.showWarnings": true,
"phpcs.showSources": true,
"phpcs.ignorePatterns": [
    "**/.git/**",
    "**/.svn/**",
    "**/.hg/**",
    "**/CVS/**",
    "**/.DS_Store/**",
    "**/node_modules/**",
    "**/bower_components/**",
    "**/storage/**",
    "**/resources/views/**",
    "**/database/migrations/**",
    "**/tests/**",
    "**/storage/framework/views/**",
    "**/vendor",
    "_ide_helper.php",
    "_ide_helper_models"
]

Step 4. PHPDoc Block settings

"php-docblocker.returnGap": true,
"php-docblocker.qualifyClassNames": true,
"php-docblocker.author": {
    "name": "Ryan McCullagh", 
    "email": "ryan@amezmo.com"
}

Step 5. Optional settings.

These settings are more of a more personal flavor, but I’ve shared them here because I believe they are amazing.

"search.collapseResults": "alwaysCollapse",
"search.exclude": {
    "**/node_modules": true,
    "**/bower_components": true,
    "**/.git": true,
    "**/storage": true,
    "**/tests": true,
    "_ide_helper.php": true,
    "_ide_helper_models.php": true,
    "package-lock.json": true
},
"files.eol": "\n",
"files.insertFinalNewline": true,
"files.trimTrailingWhitespace": true,
"files.associations": {
    "*.blade.php": "html",
    "*.php": "php",
    "*.vue": "vue",
    "*.php-cs": "php"
},
"editor.fontSize": 14,
"editor.letterSpacing": 0.5,
"editor.lineHeight": 24,
"editor.cursorBlinking": "smooth",
"editor.fontLigatures": false,
"editor.formatOnType": false,
"editor.formatOnPaste": false,
"editor.autoIndent": "advanced",
"git.showPushSuccessNotification": true,
"editor.gotoLocation.multipleDefinitions": "goto",
"editor.snippetSuggestions": "bottom",
"workbench.editor.enablePreview": false,
"workbench.editor.enablePreviewFromQuickOpen": false,

The last 2 are great because the editor will stay open when you’ve navigated to a file from a find all reference, or go to definition click.