Snippet Injection

In some cases, you may want to add your code blocks into the generated source code files. Or you may want to disable a generated code block and add your code block into the source code files. In such cases, the Snippet Injection method offers a practical solution.

Immediately after the source code generation process, Pyronome automatically runs the Snippet Injection process and injects desired code blocks into the generated source code where necessary.

The snippet injection system consists of two parts:

1. Snippet Injection Identifier
2. snippets Directory Structure

Snippet Injection Identifier is a special string that begins with {{@snippet:, which is added in the pattern templates or static files. These identifiers are replaced with the source code files saved into the snippets directory based on snippet Directory Structure. snippets Directory Structure is the collection of files and directories with special naming and content. These files and directories determine how to add the code blocks into the source code.

Snippet Injection Identifier

Snippet Injection Identifiers determine the exact location where the code block will be replaced in the source code file. These identifiers are added by the users who create the pattern and static files. Snippet Injection Identifiers start with {{@snippet:. Thus, during the snippet injection process, Pyronome easily finds out these identifiers and inserts the desired code block into the source code.

For example:

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\RouteServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Route;
use App\Http\Middleware\HTMLDBMiddleware;
use App\Http\Middleware\AdminLTEMiddleware;

class RouteServiceProvider extends ServiceProvider
{

    /* {{@snippet:begin_methods}} */

    /**
     * This namespace is applied to your controller routes.
     *
     * In addition, it is set as the URL generator's root namespace.
     *
     * @var string
     */
    protected $namespace = 'App\Http\Controllers';

In the source code above, {{@snippet:begin_methods}} is the snippet injection identifier. In this identifier, begin_methods specifies the name of the snippet injection identifier.

Note:

Depending on the type of source code file, comment block open/close characters can be added at the beginning and end of the snippet injection identifier. In the snippet injection process, the line that passes the snippet injection identifier is FULLY DELETED, and the desired code block is overwritten to this line.

snippets Directory Structure

The source code generated by the Pyronome source code generators has a directory structure similar to the following:

├── pyronome
├── snippets *
└── source

There are two directories named system and user in the snippets directory within the generated source code:

├── pyronome
├── snippets
│   ├── system *
│   └── user *
└── source

The system directory in thesnippets directory was created to be used by patterns installed on the projects. The user directory has also been created for the snippets to be added by the project user. Firstly, the system directory snippets are injected into the project source code; after then, the user directory snippets are injected.

For example: Suppose that the following source code file is located in the source/app/Providers/ directory with the file name RouteServiceProvider.php.

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\RouteServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Route;
use App\Http\Middleware\HTMLDBMiddleware;
use App\Http\Middleware\AdminLTEMiddleware;

class RouteServiceProvider extends ServiceProvider
{

    /* {{@snippet:begin_methods}} */

    /**
     * This namespace is applied to your controller routes.
     *
     * In addition, it is set as the URL generator's root namespace.
     *
     * @var string
     */
    protected $namespace = 'App\Http\Controllers';

If we want to add the following comment line instead of the code line /* {{@snippet:begin_methods}} */ in the RouteServiceProvider.php file above:

    /* THIS COMMENT ADDED USING SNIPPET INJECTION */

Firstly, we need to create the directory source/app/Providers/ into the user directory below; after then, RouteServiceProvider.php DIRECTORY should be created in the snippets/user/source/app/Providers/ directory:

├── pyronome
├── snippets
│   ├── system
│   └── user *
└── source

After creating the directories, they have a directory structure like the one below:

├── pyronome
├── snippets
│   ├── system
│   └── user
│       └── source
│           └── app
│               └── Providers
│                   └── RouteServiceProvider.php
└── source

A directory named begin_methods -the name of the snippet injection identifier- should be created in the RouteServiceProvider.php directory. A file with the name 0000.php should also be created in this directory. The comment lines mentioned above should be saved into the `0000.php'.

├── pyronome
├── snippets
│   ├── system
│   └── user
│       └── source
│           └── app
│               └── Providers
│                   └── RouteServiceProvider.php
│                       └── begin_methods
│                           └── 0000.php
└── source

The following comment lines should be saved into the file 0000.php created above.

    /* THIS COMMENT ADDED USING SNIPPET INJECTION */

As a result of the snippet injection process that runs after the source code generation process, the content of the source/app/Providers/RouteServiceProvider.php will be updated as follows:

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\RouteServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Route;
use App\Http\Middleware\HTMLDBMiddleware;
use App\Http\Middleware\AdminLTEMiddleware;

class RouteServiceProvider extends ServiceProvider
{

    /* THIS COMMENT ADDED USING SNIPPET INJECTION */

    /**
     * This namespace is applied to your controller routes.
     *
     * In addition, it is set as the URL generator's root namespace.
     *
     * @var string
     */
    protected $namespace = 'App\Http\Controllers';

Here we can create any file we want in the directory snippets/user/source/app/Providers/RouteServiceProvider.php/begin_methods. The created files will be injected in ascending natural sort order.

Since files from many different sources can be inserted into the snippets directory, some helper files can be added to organize the snippet files.

Helper File	Description
__glue__	This helper is used to specify a concatenation string that is used to join different snippets files. For example, , or ;, etc. This file content has no length or number of characters limit. If there are no snippet files in the snippets directory, this file is ignored.
__header__	This helper is used to specify the header string to be written at the beginning while merging the different snippet files. After all the files are joined, the file content of __header__ is added at the top. If there are no snippet files in the snippets directory, this file is ignored.
__footer__	This helper is used to specify the header string to be written at the end while merging the different snippet files. After all the files are joined, the file content of __footer__ is added at the bottom. If there are no snippet files in the snippets directory, this file is ignored.
__default__	This helper is used to specify default content if there are no files in the snippets directory. If there is a file in the directory of snippets, this file is ignored.

For example: Suppose that, we want to add two files named 0010.php and 0020.php in the directory snippets/user/source/app/Providers/RouteServiceProvider.php/begin_methods as we added the file 0000.php.

Let's add the file 0010.php as follows:

├── pyronome
├── snippets
│   ├── system
│   └── user
│       └── source
│           └── app
│               └── Providers
│                   └── RouteServiceProvider.php
│                       └── begin_methods
│                           ├── 0000.php
│                           └── 0010.php
└── source

Let's save the following comment lines into the 0010.php file:

    /* THIS COMMENT ADDED USING SNIPPET INJECTION FILE 0010.php */

Likewise, let's add the file 0020.php:

├── pyronome
├── snippets
│   ├── system
│   └── user
│       └── source
│           └── app
│               └── Providers
│                   └── RouteServiceProvider.php
│                       └── begin_methods
│                           ├── 0000.php
│                           ├── 0010.php
│                           └── 0020.php
└── source

Let's save the following comment lines into the 0020.php file:

    /* THIS COMMENT ADDED USING SNIPPET INJECTION FILE 0020.php */

Let's add __header__, __footer__ and __glue__ files as follows:

├── pyronome
├── snippets
│   ├── system
│   └── user
│       └── source
│           └── app
│               └── Providers
│                   └── RouteServiceProvider.php
│                       └── begin_methods
│                           ├── __footer__
│                           ├── __glue__
│                           ├── __header__
│                           ├── 0000.php
│                           ├── 0010.php
│                           └── 0020.php
└── source

Let's save the following lines into the file __header__:

    /* --- HEADER --- */

Let's save the following lines into the file __footer__:

    /* --- FOOTER --- */

Let's save the following lines into the file __glue__:

    /* --- GLUE --- */

As a result of the snippet injection process that runs after the source code generation process, the file content of source/app/Providers/RouteServiceProvider.php will be updated as follows.

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\RouteServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Route;
use App\Http\Middleware\HTMLDBMiddleware;
use App\Http\Middleware\AdminLTEMiddleware;

class RouteServiceProvider extends ServiceProvider
{

    /* --- HEADER --- */
    /* THIS COMMENT ADDED USING SNIPPET INJECTION */
    /* --- GLUE --- */
    /* THIS COMMENT ADDED USING SNIPPET INJECTION FILE 0010.php */
    /* --- GLUE --- */
    /* THIS COMMENT ADDED USING SNIPPET INJECTION FILE 0020.php */
    /* --- FOOTER --- */

    /**
     * This namespace is applied to your controller routes.
     *
     * In addition, it is set as the URL generator's root namespace.
     *
     * @var string
     */
    protected $namespace = 'App\Http\Controllers';