eloverde/laravel-file-generator

Laravel file generator

This is a Laravel package which helps you automate creation of files.

Benefits

• If you create a type of file frequently, you can automate it and improve productivity.
• Prevent "context switching" where you lose focus for 30 seconds while you create new files, directories and populate it with boilerplate.
• Comes with several built-in boilerplates. Easy to share your own as github gists.
• All boilerplates and generators are part of your repository, letting you share standard templates with your team.
• Find things like artisan make:model and artisan make:controller useful? You can make your own.
• All boilerplates can be written as blade templates.

Quick Start

Step 1: Install the package

$ composer require skyronic/laravel-file-generator

Step 2: Publish the "boilerplates" - an included set of useful boilerplates like PHP Classes.

$ php artisan vendor:publish --tag='boilerplates'

Step 3: You can list all the installed boilerplates

$ php artisan generate:list

+---------------+------------------------------+
| Type          | Name                         |
+---------------+------------------------------+
| css           | CSS File                     |
| js            | JavaScript File              |
| php:class     | PHP Class in 'app' Directory |
| php:trait     | PHP Trait in 'app' Directory |
| view          | Blade Template               |
+---------------+------------------------------+

Use `artisan generate <type>` to create a new file!

Step 5: You can create a php class now:

$ php artisan generate php:class "Support/Helpers/AwesomeHelper" --extends "BaseHelper" --constructor

Created file [ app/Support/Helpers/AwesomeHelper.php ]

The generator php:class creates one by default in. You can now open app/Support/Helpers/AwesomeHelper.php

<?php

namespace App\Support\Helpers\AwesomeHelper;

class AwesomeHelper extends BaseHelper  {
    public function __construct () {

    }
}

Step 6: Create your own template:

$ php artisan generate:new mytemplate --description "My New Template"

Created new boilerplate at [ resources/boilerplates/mytemplate.boilerplate.txt ]

Understanding Boilerplate Template

Open the file created by Step 6. You will see something like this:

{
   "name": "My Template",
   "out": "edit/me/{{ $name }}.txt",
   "params": {
        "myParam": "optional"
   }
}
---

Template goes here. Blade syntax works. You can use a parameter like {{ $myParam }}

There's two parts to the file, separated by ---.

• The top part is the configuration of how the template should behave, and also specifying parameters
• The bottom part is the actual template which will be.

The configuration object

Let's take a closer look at this config object:

{
   "name": "My Template",
   "out": "edit/me/{{ $name }}.txt",
   "params": {
        "myParam": "optional"
   }
}

This should be valid JSON. The key name is the name of the template used for generate:list. Not to be confusued with the $name variable.

Setting Output Path

If you try to run the template with something like:

$ php artisan generate mytemplate foo/bar

The output path here will be: edit/me/foo/bar.txt. $name contains the second parameter, and even the strings can use blade so {{ $name }} will produce the path.

Parameters

Parameters allow you to customize and change the content of the file. For example, here we have myParam. So running this boilerplate with

$ php artisan generate mytemplate foo/bar --myParam "Hello"

Will result in the text file:

Template goes here. Blade syntax works. You can use a parameter like Hello

Flag Parameters

Here's a simple template (some elements omitted for brevity).

"params": {
    "someFlag": "optional"
}
---
This is always visible.

@if($someFlag)
This is only visible when the flag is set
@endif

Now we can run it like:

# $someFlag will be set to false
$ php artisan generate mytemplate foo/bar 

# $someFlag will be set to true
$ php artisan generate mytemplate foo/bar --someFlag

Required Parameters

"params": {
    "className": "required"
}
---
class {{ $className }} {
   
}

$ php artisan generate mytemplate foo/bar

  [Skyronic\FileGenerator\FileGeneratorException]
  Needs argument [ className ]

Optional Parameters

"params": {
    "authorName": "optional"
}
---
@if($authorName)
/* Author: {{ $authorName }} */
@endif
class MyClass {
   
}

You can recognize the if and endif as blade conditional structures. If authorName is set like:

$ php artisan generate mytemplate foo/bar --authorName John

Then the value is set to "John". Else it's null.

Default Values

If you set the parameter to anything except flag or optional or required it's considered a default value.

"params": {
    "copyrightYear": "2017"
}
---

/* Copyright (c) {{ $copyrightYear }} */

The value is going to be set to 2017 unless specified otherwise.

# Set to default value of 2017
$ php artisan generate mytemplate foo/bar

# Override the value to 2016
$ php artisan generate mytemplate foo/bar --copyrightYear 2016

Tips for writing boilerplates

• A template like vue__component.boilerplate.txt will become vue:component for cleaner organization. You can use __ in your own templates.
• Important: Pass a --dry-run flag like php artisan generate --dry-run mytemplate foo/bar --myParam "paramvalue" to display the output in console. This lets you iterate and fix any potential issues without creating files.
• You can use most of laravel's helper functions and even some other PHP classes with some advanced blade and the @php directive
• You can use paths like foo/bar/{{ $name }} and FileGenerator will automatically adjust directory separators on windows.

If you're using this tool to generate blade files, using keywords like @section and @extends might not work. Instead use @@section and @@extends

For example:

{
   "name": "Blade Template",
   "out": "resources/views/{{ $name }}.blade.php",
   "params": {
       "title": "required"
   }
}
---
@@extends('layouts.main')
@@section("title", '{{ $title }}')

@@section('content')

@@endsection

Formatter

Sometimes you might need to do some string manipulation. Later versions of File Generator will contain more comprehensive string manipulation later.

Camel-case, Snake-case, etc

You can use Laravel's built in helpers for things like camel_case and others.

Basename from path

If you've got something like app/Support/MyHelper.php and want to extract MyHelper you can use Format::baseName ($path) which extracts a classname like entity, ignoring any file extension.

Getting a namespace from path

Namespaces are a bit tricky, since they need to render forward-slashes. FileGenerator contains a simple format helper which can generate a namespace from a given file path. It uses the laravel app directory and App namespace by default.

// $path = "app/Support/Helpers/AwesomeHelper.php"
Format::getNamespace ($path)
// -> "App\Support\Helpers"

// For non `app` directories, you need to manually specify namespace routes
// $path = "tests/Unit/HelperTests/AwesomeHelperTest.php"
Format::getNamespace ($path, 'tests', "Tests")
// -> "Tests\Unit\HelperTests"

Example: PHP Class generator

First, be sure that you've run php artisan vendor:publish --tag='boilerplates' and check app/resources/boilerplates/php__class.boilerplate.txt

{
   "name": "PHP Class in 'app' Directory",
   "out": "app/{{ $name }}.php",
   "params": {
       "extends": "optional",
       "constructor": "flag"
   }
}
---
<?php

namespace {{ Format::getNamespace($path) }};

class {{ Format::baseName($name) }} @if($extends)extends {{ $extends }}@endif  {
@if($constructor)
    public function __construct () {

    }
@endif
}

The example should be pretty self explanatory. But can illustrate that even a little blade templating can go a long way.