Scaffold Documentation

Transcription

1 Scaffold Documentation Release 1.1 Alin Eugen Deac Oct 29, 2017

2

3 Contents 1 Contents How to Install Install Scaffolds Create Scaffolds Release Notes Indices i

4 ii

5 How many times have you been doing the same task, over and over again? Maybe it s time for you to create some kind of helper that can perform that task for you. Perhaps this tool might be able to help you along the way. Scaffold is a php-based command line tool for creating and installing various files and directories into your project, based on a configuration file (scaffold). Key features Create desired directory structure Copy static files into desired location Ask user for input Generate files based on templates, compiled with data from the user In other words, you can perceive this tool as a console wizzard for installing something inside your project. Source is available on GitHub. Contents 1

6 2 Contents

7 CHAPTER 1 Contents The basics How to Install Requirements php version > composer This package uses composer. If you do not know what that is or how it works, I recommend that you read a little about, before attempting to use this package. Other than this, you scaffold application requires read / write access to the directories where you use it. Normally this isn t a problem. However if you run into these kinds of issues, please review your PHP s access privileges. Local Installation The Scaffold application is intended as a development tool, which is why it should be required via composer as a development dependency. composer require aedart/scaffold --dev Global Installation A global installation allows you to use the scaffold application everywhere. composer global require aedart/scaffold 3

8 Warning: If you have other packages installed globally, their dependencies might conflict. You can perhaps resolves this by making use of Consolidation/Cgr, which safely installs each command line tool application in it s own directory. How to use scaffolds Install Scaffolds Require Scaffold Regardless if you are within a new project or existing, you must first require your desired scaffold(s). This is done via composer s require command or by specifying it in your composer.json. composer require acme/scaffolds { } "name": "acme/my-project", "description": "My Proejct", "license": "BSD-3-Clause", "type": "library", "require": { "acme/scaffolds": "~1.0" }, Global Scaffolds If you have chosen to require your scaffold(s) globally, then they should already be available and there is no need for you to perform this. Install Scaffold Install Command The easiest way to install a your desired scaffold, is by invoking the install command vendor/bin/scaffold install This command will automatically create an index of all the found scaffolds and start displaying a list of vendors, packages and scaffolds you can chose to install. It should output something similar to this; Building index ==============! [NOTE] Building new index (.scaffold/index.json) Searching in /home/code/my-project/vendor! [NOTE] Indexing /home/code/my-project/vendor/acme/scaffolds/my-scaffold.scaffold. php 4 Chapter 1. Contents

9 Searching in /home/.composer/vendor! [NOTE] No scaffolds found in /home/.composer/vendor [OK] Indexing completed Install... ========== Please select a vendor: [0] acme > Tip: The install command supports several options. See command help for additional information. vendor/bin/scaffold install -h Build Command If you wish to skip the install procedure (listing of vendors, packages... etc), then you can use the build command to specify your desired scaffold directly. vendor/bin/scaffold build other/location/my-scaffold.scaffold.php Build From File Command Sometimes it can be useful to automate the building process. For instance, if you want to build several scaffolds at once, then you can use the build:file command. vendor/bin/scaffold build:file location/scaffoldstobuild.php The command accepts a single argument, file, which is a location to a php file that contains a list of scaffolds to be built. In other words, this command allows you to build multiple scaffolds in one and the same process. File Format The following illustrates the format that the build:file command accepts. [ // Location to scaffold 'location' => DIR. '/MyModel.scaffold.php', // Input (answers to questions) for that scaffold 'input' => [ 1.2. Install Scaffolds 5

10 [ [ ] 'AEDART/a' 'location' => DIR. '/MyController.scaffold.php', 'input' => [ 'Acme/b' ] 'location' => DIR. '/MyView.scaffold.php', 'input' => [ 'Punk/c' ] Output Location By default, bot the install and the build commands will output the resulting files and directories into the current working directory, form where you invoked the command. This behaviour can be modified by providing the commands with an optional output directory vendor/bin/scaffold install -o path/where/to/install/ vendor/bin/scaffold build -o path/where/to/install/ other/location/my-scaffold. scaffold.php Create your own Create Scaffolds Location The first thing you need to consider is, where to place your scaffold files. Regardless of your choice, I recommend that you use a version control system! Note: Make sure that the scaffold application is available a development dependency. See How to Install New Project The safest options is to create a new repository in which you only have to deal with the scaffold and it s resources. Doing so allows you to focus mainly on the structure of the scaffold and there is little risk for you to interfere with existing files. 6 Chapter 1. Contents

11 Tip: If you are new to using this application, then I recommend that you start off by creating scaffolds in a separate project. Existing Project Alternatively, you can also create scaffolds directly into existing projects. This does have the benefit of having a tight coupling between your project and associated scaffolds. However, be sure of what you are doing, as it is the nature of this application to write files! Location of (*).scaffold.php The *.scaffold.php file is covered in the upcoming chapters. For now, you just need to ensure that it is located in the project s root directory, at the same level as your composer.json. The reason why the scaffold configuration file (*.scaffold.php) needs to be located here, is due to the indexing performed by the application. By default, it will search for scaffolds inside the local vendor directory, searching each package s root directory only! Blank Scaffold To create a blank scaffold, execute the following command; vendor/bin/scaffold install -a Select the Blank Scaffold (aedart/scaffold) scaffold to be installed and follow the onscreen guide. Once completed, you should have a new empty *.scaffold.php file and a resources directory. (*).scaffold.php The *.scaffold.php file is the configuration file (a php array) that the scaffold application will read and execute upon installation. In short, it determines what will happen when an end-user installs it. 'name' 'description' => 'My Scaffold', => 'Creates cool stuff', 'basepath' => DIR. '/resources/', 'tasks' => [ 'folders' => [ 'files' => [ 'templatedata' => [ 'templates' => [ 1.3. Create Scaffolds 7

12 'scripts' => [ 'handlers' => [ In the following sections, each of the above properties is covered in detail. Name required yes Name of the Scaffold. The name is displayed in the list of available templates, when the install command is invoked. 'name' => 'My Scaffold', Description required yes Description of the scaffold. The description is displayed in the list of available templates, when the install command is invoked. 'description' => 'Creates a few things...', BasePath required yes Location of scaffold s resources, e.g. static files and templates. This path tells the scaffold where it can find it s resource, from which it can build and install one or several folders, files and or templates. 'basepath' => DIR. '/resources/', 8 Chapter 1. Contents

13 Tasks required yes An ordered list of all the tasks that must be executed. These tasks are responsible for building your project or resource. By default, several tasks are included in a blank scaffold. You can change these are you see fit, but keep in mind that the order does matter. 'tasks' => [ \Aedart\Scaffold\Tasks\AskForTemplateData::class, \Aedart\Scaffold\Tasks\AskForTemplateDestination::class, \Aedart\Scaffold\Tasks\CreateDirectories::class, \Aedart\Scaffold\Tasks\CopyFiles::class, \Aedart\Scaffold\Tasks\GenerateFilesFromTemplates::class, Note: You can remove all of the default tasks and replace them with your own. When creating custom tasks, just ensure that you implement the \Aedart\Scaffold\Contracts\Tasks\ConsoleTask interface. You can also just extend the \Aedart\Scaffold\Tasks\BaseTask abstract task, which does some of the ground work for you. Please review the documentation inside the source code for further information. Folders required only if \Aedart\Scaffold\Tasks\CreateDirectories::class is used List of directories (or folders) that will be created. 'folders' => [ 'app', 'config', 'src' => [ 'Contracts', 'Controllers', 'Events', 'Models', 'tmp' 1.3. Create Scaffolds 9

14 Files required only if \Aedart\Scaffold\Tasks\CopyFiles::class is used Copies files from basepath and into the output directory. See BasePath 'files' => [ // Source files (inside 'basepath') => Destination '.gitkeep' => '.gitkeep', 'logs/default.log' => 'tmp/log.log', 'docs/license.txt' => 'LICENSE', Warning: You should avoid large files. If your template requires such, then you should perhaps consider a custom task that can download them from an external source! Alternatively, you can use scripts to perform large file downloads. Just remember to specify a timeout. See Scripts TemplateData required a b c only if the following tasks are used \Aedart\Scaffold\Tasks\AskForTemplateData::class, \Aedart\Scaffold\Tasks\AskForTemplateDestination::class, \Aedart\Scaffold\Tasks\GenerateFilesFromTemplates::class Data to be used inside Twig templates. Depending upon the template-data s type, the end-user might be asked in the console for an answer. You can specify as many template data entries as you wish. 'templatedata' => [ 'myproperty' => [ 'value' => 'My property value' 10 Chapter 1. Contents

15 Syntax 'templatedata' => [ 'name-of-property' => [ 'type' => \Aedart\Scaffold\Contracts\Templates\Data\Type::QUESTION 'question' => 'The question to ask the user' 'value' => (default value, in case user just hits enter), 'validation' => function($answer){return $answer;}, $answer;}, ] 'postprocess' => function($answer, array $previousanswers){return The postprocess callback method is automatically provided with eventual previous values. This gives you the possibility creating computed values that combine previous given answers from the end-user. The postprocess is available for all supported types. In the following sections, an example is shown on each supported type. Question 'templatedata' => [ 'myquestion' => [ 'type' => \Aedart\Scaffold\Contracts\Templates\Data\Type::QUESTION, 'question' 'value' => 'What is your vendor name? (used as namespace prefix)', => 'Acme', 'validation' => function($answer){ if(strlen($answer) >= 3){ return $answer; } long'); }, throw new \RuntimeException('Vendor name should be at least 3 chars 'postprocess' => function($answer, array $previousanswers){ return ucfirst($answer); } 1.3. Create Scaffolds 11

16 Choice 'templatedata' => [ 'mychoice' => [ 'type' 'question' => \Aedart\Scaffold\Contracts\Templates\Data\Type::CHOICE, => 'In what sub-namespace should your class be located?', 'choices' => [ 'Controllers', 'Events', 'Models' 'value' => 'Controllers', Confirm 'templatedata' => [ 'myconfirm' => [ 'type' => \Aedart\Scaffold\Contracts\Templates\Data\Type::CONFIRM, 'question' => 'Add class PHPDoc?', 'value' => true, Hidden 'templatedata' => [ 'mypassword' => [ 'type' 'question' => \Aedart\Scaffold\Contracts\Templates\Data\Type::HIDDEN, => 'What password should be stored inside the.env?', 12 Chapter 1. Contents

17 'validation' => function($answer){ if(strlen($answer) >= 6){ return $answer; } throw new \RuntimeException('The password should be at least 6 characters long'); }, Value When using a simple value, the end-user is not prompted with any questions. Also, the type does not have to be declared explicitly. 'templatedata' => [ 'myvalue' => [ 'value' => 'My Value' It is also possible to perform post-processing of simple values. It can be used to create a computed value which consists of the given value and perhaps a previously given value. 'templatedata' => [ 'myvalue' => [ 'value' => 'My Value', 'postprocess' => function($answer, array $previousanswers){ return $answer. $previousanswers['myothervalue' } Templates required only if the following tasks are used a \Aedart\Scaffold\Tasks\AskForTemplateData::class, b \Aedart\Scaffold\Tasks\AskForTemplateDestination::class, c \Aedart\Scaffold\Tasks\GenerateFilesFromTemplates::class The snippets (or templates) from which one or several files must be generated from. Each defined template assumes that it s source Twig template is located inside the basepath. See BasePath 1.3. Create Scaffolds 13

18 'templates' => [ 'mytemplate' => [ 'source' => 'snippets/env.twig', 'destination' => [ 'value' => '.env', Ask for template destination The destination property works in the same way as with the templatedata, in that you can use it to ask the end user for a file destination. All types are supported. See TemplateData. 'templates' => [ 'mytemplate' => [ 'source' => 'snippets/markdown.twig', // Destination of a file - uses a "question" property 'destination' => [ 'type' => \Aedart\Scaffold\Contracts\Templates\Data\Type::QUESTION, ', 'question' 'value' => 'Name / location of file? (.md automatically added) => 'WIKI', // Use post processing to add file extension 'postprocess' => function($answer, array $previousanswers){ return $answer. '.md'; } Scripts required only if \Aedart\Scaffold\Tasks\ExecuteScripts::class is used CLI scripts (or commands) to be executed Scripts can be used to perform advanced operations. This could for instance be downloading large files, disk cleanup, running composer commands... etc. 14 Chapter 1. Contents

19 Multiple scripts are allowed and they can be stated in several ways. Simple Script 'scripts' => [ 'composer update', ] Script with Timeout If yor expect your script(s) to require more that 60 seconds, then consider specifying a custom timeout. 'scripts' => [ [ 'timeout' => 75, // Default is 60 seconds 'script' => 'composer install && composer update' ] Advanced Script If you need to perform very advanced scripts that depends on the scaffold configuration, then you can achieve this via an anonymous function. A copy of the scaffold configuration is given as argument. The function MUST return an instance of \Aedart\Scaffold\Contracts\Scripts\CliScript. 'scripts' => [ function(array $config){ $script = 'cd '. $config['outputpath']. ' && ls'; ] }, return new \Aedart\Scaffold\Scripts\CliScript([ 'timeout' => 10, 'script' => $script ]); Error when triggering composer commands If you trigger some kind of composer script, then you might see that composer s output is logger to the console as an error. This is due to that composer chooses to write diagnostic output to STDERR instead of STDOUT Create Scaffolds 15

20 You can read more about this in #1905 and #3795. Handlers required no These handlers are used by some of the default tasks. They provide an additional level of flexibility, in which you can use the default tasks, yet change the way that each of them handles certain operations. If you do not plan to change the default tasks behaviour, then you can leave out this part of the configuration. 'handlers' => [ 'directory' => \Aedart\Scaffold\Handlers\DirectoriesHandler::class, 'file' => \Aedart\Scaffold\Handlers\FilesHandler::class, 'property' => \Aedart\Scaffold\Handlers\PropertyHandler::class, 'template' => \Aedart\Scaffold\Handlers\TwigTemplateHandler::class, 'script' => \Aedart\Scaffold\Handlers\ScriptsHandler::class, ] Note: You can create your own handlers, if the default handlers are insufficient to cover your needs. Handlers need to implement the \Aedart\Scaffold\Contracts\Handlers\Handler interface. Alternatively, you can extend the \Aedart\Scaffold\Handlers\BaseHandler abstract handler. It should provide you with a few common methods implementation. Tip: Currently, only Twig templates are supported. If you do not like working with that engine, then you can implement a different one, by means of creating a new template handler (Please review \Aedart\Scaffold\Handlers\TwigTemplateHandler for inspiration). If this is the case, please consider if making that handler publicly available for others :) Testing Depending on your scaffold complexity, the fastest way of testing it is manually, by building it locally. vendor/bin/scaffold install -a -o temp/ The above command will first index your scaffold and thereafter install it. All of it s output will go into the temp directory. Automatic Testing If your scaffold(s) have become very complex, require lots of user input or perhaps depend on many resources, then perhaps it is better to write some kind of automatic test for, e.g. via PHPUnit. The current version of the scaffold application does not offer any testing utilities. However, you can review the tests\integration\installcommandtest as inspiration on how to write automatic tests for your scaffold. Behind the scenes, Symfony s Command Tester is being used. 16 Chapter 1. Contents

21 In future versions, this package might include better testing utilities. Helpers Since version a helpers.php file is included, which offers a few utility methods that can be used throughout your scaffold. The file is located in {{scaffold application location}}\helpers\helpers.php. Cache Available since version Confronting an end-user with too many questions can quickly become a hassle for them. Therefore, if you find yourself in a situation where you need a lot of user input, consider caching some of the input. Caching is made available in a scaffold, by making use of the scaffold_cache_* methods, which are defined inside the helpers.php file. Behind the Scene The caching system that is offered by the Scaffold Application, is basically just a wrapper around Laravel s Cache. It is configured to use the \Illuminate\Cache\FileStore, storing values withing the user provided cache directory. The cache directory is set via a --cache option on each available command that makes use of caching. It defaults.scaffold/cache/ if the option is not provided. Example In this example, once a user has answered the question first time, the scaffold will use a cached answer as the default value. Next time the scaffold is built, the default value will become the cached value. 'templatedata' => [ 'name' => [ 'type' => \Aedart\Scaffold\Contracts\Templates\Data\Type::QUESTION, 'question' 'value' => 'What is your name?', => scaffold_cache_get('name', 'John Doe'), 'postprocess' => function($answer, array $previousanswers){ // Update the cached value, in case user provides a "new" answer scaffold_cache_put('name', $answer, 60); } return $answer; 1.3. Create Scaffolds 17

22 Available Methods Please consider Laravel s documentation for further information and examples of using the cache. scaffold_cache() Returns an instance of \Illuminate\Contracts\Cache\Repository. scaffold_cache_put($key, $value, $minutes = 5) Store an item in the cache. scaffold_cache_remember($key, $minutes, Closure $callback) Get an item from the cache, or store the default value. scaffold_cache_forever($key, $value) Store an item in the cache indefinitely. scaffold_cache_has($key) Determine if an item exists in the cache. scaffold_cache_get($key, $default = null) Retrieve an item from the cache by key. scaffold_cache_pull($key, $default = null) Retrieve an item from the cache and delete it. scaffold_cache_forget($key) Remove an item from the cache. scaffold_cache_flush() Flushes the registered cache directory. Misc 18 Chapter 1. Contents

23 Release Notes Within this chapter, you will find a list of the most significant changes. Version 2.0.x v2.0.1 ( ) Fixed Incorrect populate of directories collection inside TwigTemplateHandler v2.0.0 ( ) Added Added build:file command Changed Changed minimum required PHP version to 7.1.x Adapted application to use Laravel 5.5.x. Several interfaces and service providers have changed. Adapted application to use Symfony 3.3.x components. Deprecated AedartScaffoldTestingConsoleStyleExtendedStyle, replaced by AedartScaffoldConsoleStyleExtendedStyle. Changed build command, now supports setting answers to questions via the input option. Version 1.2.x v1.2.0 ( ) Changed License updated Version 1.1.x v1.1.5 ( ) Fixed Re-fixed indexing order. First fix was correct, yet due to incorrect manual test, the issue didn t seemed fixed Release Notes 19

24 v1.1.4 ( ) Fixed Re-fixed order of default indexing directories. First fix caused undesired indexing results. v1.1.3 ( ) Fixed Fixed order of default index directories. v1.1.2 ( ) Fixed Fixed #4 Parse error: syntax error, unexpected -> (T_OBJECT_OPERATOR) (issue in PHP 5.6.x only) v1.1.1 ( ) Fixed Fixed Fatal error: Can t use function return value in write context (issue in PHP 5.6.x only) v1.1.0 ( ) Added Added Cache utility (#3). Added release notes documentation Added multiple smaller and more maintainable service providers Added documentation about why output from composer commands (in scripts) are logged to STDERR Changed Changed ScaffoldServiceProvider, has now become an AggregateServiceProvider instead. It registers a series of smaller service providers. Version 1.0.x v1.0.4 ( ) Fixed Fixed ScriptHandler logging of empty buffer 20 Chapter 1. Contents

25 v1.0.3 ( ) Fixed Fixed ScriptHandler dual logging of buffered output v1.0.2 ( ) Fixed Fixed console logging attempted converting array into string v1.0.1 ( ) Changed Changed required dependencies Fixed Fixed property value being cast to string, which caused issue for other types of values, e.g. arrays Fixed unstable tests, due to poor generated sample data v1.0.0 ( ) Release of first stable version Indices genindex 1.5. Indices 21

26 22 Chapter 1. Contents

27 Index B BasePath scaffold.php, 8 Blank Empty Scaffold, 7 Build Command, Install, 4 Build-File File Command, 4 C Cache, 17 CLI, 14 Command Build-File File, 4 Install Build, 4 Command Tester Symfony, 16 Composer STDERR, 14 STDOUT, 14 D Description scaffold.php, 8 E Empty Scaffold, Blank, 7 Scaffold, Location, 6 F File Command, Build-File, 4 Files scaffold.php, 9 Folders scaffold.php, 9 G Global Installation, 3 H Handlers scaffold.php, 16 helpers, 17 I Install Build Command, 4 Installation Global, 3 Local, 3 L Local Installation, 3 Location Empty Scaffold, 6 Output, 4 Scaffold, 6 N Name scaffold.php, 8 New Scaffold, 7 O Output Location, 4 P PHPUnit UnitTest, 16 R Release Notes, 18 23

28 Require Scaffold, 4 Requirements, 3 S Scaffold Blank Empty, 7 Location, 6 Location Empty, 6 New, 7 Require, 4 scaffold.php, 6, 7 BasePath, 8 Description, 8 Files, 9 Folders, 9 Handlers, 16 Name, 8 Scripts, 14 Tasks, 8 TemplateData, 10 Templates, 13 Scripts scaffold.php, 14 Single: Build, 4 Single: Build-File, 4 Single: Install, 4 STDERR Composer, 14 STDOUT Composer, 14 Symfony Command Tester, 16 T Tasks scaffold.php, 8 TemplateData scaffold.php, 10 Templates scaffold.php, 13 Testing, 16 U UnitTest PHPUnit, Index