adhocore / phint
Initializes new PHP project with sane defaults using templates
Fund package maintenance!
adhocore
paypal.me/ji10
Requires
- php: >=7.1
- adhocore/cli: ^0.8.1
- adhocore/json-comment: ^0.1
- crazyfactory/docblocks: ^2.2
- symfony/finder: ^3.3.0
- twig/twig: ^2.4.0
Requires (Dev)
- phpunit/phpunit: ^6.0
- dev-master
- 0.6.1
- 0.6.0
- v0.5.4
- v0.5.3
- v0.5.2
- v0.5.1
- v0.5.0
- v0.4.1
- v0.4.0
- v0.3.6
- v0.3.5
- v0.3.4
- v0.3.3
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.1
- v0.2.0
- v0.1.1
- v0.1.0
- v0.0.13
- v0.0.12
- v0.0.11
- v0.0.10
- v0.0.9
- v0.0.8
- v0.0.7
- v0.0.6
- v0.0.5
- v0.0.4
- v0.0.3
- v0.0.2
- v0.0.1
- dev-dependabot/composer/adhocore/json-comment-tw-0.1or-tw-1.0
- dev-dependabot/composer/adhocore/cli-tw-0.8.1or-tw-0.9.0
- dev-main
- dev-dependabot/composer/phpunit/phpunit-tw-6.0or-tw-7.0
- dev-develop
This package is auto-updated.
Last update: 2024-09-25 18:01:20 UTC
README
Initializes new PHP project with sane defaults using templates. It scaffolds PHP library &/or project to boost your productivity and save time.
For already existing project, run with --sync
flag to add missing stuffs, see phint init.
Once you have files in your src/
or lib/
you can run phint docs to generate API like documentation in .md
format
and phint test to generate basic test stubs with all the structures already maintained.
It helps you be even more lazier! phint is continuously evolving and the plan is to make it big.
Installation · Features · Autocompletion · Usage · phint init · phint update · phint docs · phint test · Templating
Phint is powered by adhocore/cli
Installation
Requires PHP7.
Manual
Download phint.phar
from latest release.
And use it like so php /path/to/phint.phar [opts] [args]
. Hmm not cool. See Command section below.
Command
# get latest version (you need `jq`) LATEST_PHINT=`curl --silent "https://api.github.com/repos/adhocore/phint/releases/latest" | jq -r .tag_name` # download latest phint curl -sSLo ~/phint.phar "https://github.com/adhocore/phint/releases/download/$LATEST_PHINT/phint.phar" # make executable chmod +x ~/phint.phar sudo ln -s ~/phint.phar /usr/local/bin/phint # check phint --help
Features
- generate dot files the likes of
.gitignore, .travis.yml, . editorconfig
etc - generate
LICENSE
,README.md
,composer.json
- generate
CHANGELOG.md
stub,CONTRIBUTING.md
guide,ISSUE_TEMPLATE.md
andPULL_REQUEST_TEMPLATE.md
- generate binaries if any
- git init
- interactively ask and install all the dev and prod deps
- generate
phpunit.xml
, testbootstrap.php
- generate test stubs for all classes/methods corresponding to
src
(phint test
) - generate docs for all public class/methods
- export templates to chosen path so it can be customized (
phint export
) - use custom templates from a path specified by user
- update its own self (
phint update
)
Autocompletion
The phint commands and options can be autocompleted if you use zsh shell with oh-my-zsh.
Setting up auto complete:
mkdir -p ~/.oh-my-zsh/custom/plugins/ahccli && cd ~/.oh-my-zsh/custom/plugins/ahccli [ -f ./ahccli.plugin.zsh ] || curl -sSLo ./ahccli.plugin.zsh https://raw.githubusercontent.com/adhocore/php-cli/master/ahccli.plugin.zsh echo compdef _ahccli phint >> ./ahccli.plugin.zsh chmod +x ./ahccli.plugin.zsh && source ./ahccli.plugin.zsh && cd -
Dont forget to add ahccli
into plugins=(... ...)
list in ~/.zshrc
file.
Usage
It can be used to quickly spin off new project containing all basic and default stuffs. The quick steps are as follows:
# See options/arguments phint init --help # OR (shortcut) phint i -h # Below command inits a brand new PHP project in `project-name` folder in current dir # Missing arguments are interactively collected phint init project-name # You can also use config file (with json) to read option values from phint init project-name --config phint.json
Commands
Each of the commands below should be used like so:
cd /path/to/project phint <command> [--options] [args]
init
alias i
Create and Scaffold a bare new PHP project.
Parameters:
Dont be intimidated by long list of parameters, you are not required to enter any of them as arguments as they are interactively collected when required.
Also check config on how to create a reusable json config so you can use phint
like a pro.
Arguments:
<project> The project name without slashes
Options:
[-b, --bin...] Executable binaries
[-c, --no-codecov] Disable codecov
[-C, --config] JSON filepath to read config from
[-d, --descr] Project description
[-D, --dev...] Developer packages
[-e, --email] Vendor email
[-f, --force] Run even if the project exists
[-G, --gh-template] Use `.github/` as template path
By default uses `docs/`
[-h, --help] Show help
[-w, --keywords...] Project Keywords
[-L, --license] License (m: MIT, g: GNULGPL, a: Apache2, b: BSDSimple, i: ISC, w: WTFPL)
[-n, --name] Vendor full name
[-N, --namespace] Root namespace (use `/` separator)
[-g, --package] Packagist name (Without vendor handle)
[-p, --path] The project path (Auto resolved)
[-P, --php] Minimum PHP version
[-R, --req...] Required packages
[-s, --no-scrutinizer] Disable scrutinizer
[-l, --no-styleci] Disable StyleCI
[-S, --sync] Only create missing files
Use with caution, take backup if needed
[-t, --no-travis] Disable travis
[-T, --type] Project type
[-u, --username] Vendor handle/username
[-z, --using] Reference package
[-y, --year] License Year
Usage Examples:
phint init <project> --force --descr "Awesome project" --name "YourName" --email you@domain.com
phint init <project> --using laravel/lumen --namespace Project/Api --type project</comment>
phint init <project> --php 7.0 --config /path/to/json --dev mockery/mockery --req adhocore/cli
Example config
Parameters sent via command args will have higher precedence than values from config file (-C --config
).
What can you put in config? Anything but we suggest you put only known options (check $ phint init --help
)
{ "type": "library", "namespace": "Ahc", "username": "adhocore", "name": "Jitendra Adhikari", "email": "jiten.adhikary@gmail.com", "php": "7.0", "codecov": false, "...": "..." }
update
alias u
Update Phint to lastest version or rollback to earlier locally installed version.
Parameters:
Options:
[-h, --help] Show help
[-r, --rollback] Rollback to earlier version
Usage Examples:
phint update Updates to latest version
phint u Also updates to latest version
phint update -r Rolls back to prev version
phint u --rollback Also rolls back to prev version
docs
alias d
Generate docs (.md
) for all public classes and methods from their docblocks.
Ideally you would run it on existing project or after you create/update src/
files.
Parameters:
Options:
[-a, --with-abstract] Create docs for abstract/interface class
[-h, --help] Show help
[-o, --output] Output file (default README.md). For old project you should use something else
(OR mark region with <!-- DOCS START --> and <!-- DOCS END --> to inject docs)
Usage Examples:
phint docs If there is `<!-- DOCS START -->` and `<!-- DOCS END -->` region
Injects new doc in between them otherwise appends to bottom
phint d -o docs/api.md Writes to docs/api.md (Same rule applies regarding inject/append)
Sample docs
PHP code
namespace Abc; /** * This is dummy class. * * It does nothing as of now. * Maybe you could fix it? */ class Dummy { /** * Alpha beta. * * Example: * * <code> * $dummy = new Dummy; * $dummy->alpha('john', true); * // '...' * </code> * * @param string $name * @param bool $flag * * @return string|null */ public function alpha($name, $flag) { // } }
Generated Markdown
## Dummy ```php use Abc\Dummy; \``` > This is dummy class. It does nothing as of now. Maybe you could fix it? ### alpha() > Alpha beta. ```php alpha(string $name, bool $flag): string|null \``` Example: ```php $dummy = new Dummy; $dummy->alpha('john', true); // '...' \```
Preview
Dummy
use Ahc\Dummy;
This is dummy class.
It does nothing as of now. Maybe you could fix it?
alpha()
Alpha beta.
alpha(string $name, bool $flag): string|null
Example:
$dummy = new Dummy; $dummy->alpha('john', true); // '...'
test
alias t
Generate test files with proper classes and test methods analogous to their source counterparts. If a test class already exists, it is skipped. In future we may append test stubs for new methods.
Ideally you would run it on existing project or after you create/update src/
files.
Parameters:
Options:
[-a, --with-abstract] Create stub for abstract/interface class
[-h, --help] Show help
[-n, --naming] Test method naming format
(t: testMethod | m: test_method | i: it_tests_)
[-p, --phpunit] Base PHPUnit class to extend from
[-s, --no-setup] Dont add setup method
[-t, --no-teardown] Dont add teardown method
Usage Examples:
phint test -n i With `it_` naming
phint t --no-teardown Without `tearDown()`
phint test -a With stubs for abstract/interface
Sample test
Generated tests/Dummy.php
for Abc\Dummy above:
<?php namespace Abc\Test; use Abc\Dummy; use PHPUnit\Framework\TestCase as TestCase; /** * Auto generated by `phint test`. */ class DummyTest extends TestCase { /** * @var Dummy */ protected $dummy; public function setUp() { parent::setUp(); $this->dummy = new Dummy; } public function testAlpha() { $actual = $this->dummy->alpha(); // $this->assertSame('', $actual); } }
Templating
phint export --to ~/myphint
So you would like to have your own templates and customize phint
to your taste!
First you need to create a directory root (of any name, eg: myphint
) with structure that looks like:
myphint
├── CHANGELOG.md.twig
├── composer.json.twig
├── CONTRIBUTING.md.twig
├── docs
│ ├── docs.twig
│ ├── ISSUE_TEMPLATE.md.twig
│ └── PULL_REQUEST_TEMPLATE.md.twig
├── .editorconfig.twig
├── .env.example.twig
├── .gitignore.twig
├── LICENSE.twig
├── package.json.twig
├── phpunit.xml.dist.twig
├── README.md.twig
├── tests
│ ├── bootstrap.php.twig
│ └── test.twig
└── .travis.yml.twig
Note that you dont need to have all the files there in new directory just pick the ones you would like to customize and start hacking.
Luckily you dont have to create these templates yourself, just run phint export --to ~/myphint
!
Pro Tip
You can actually introduce any new template as long as their extension is .twig
.
Such templates are only used by phint init
command. Check Template variables.
After you are done customizing these templates you can use them in each of the phint commands like so
phint init project --template ~/myphint phint docs --template ~/myphint phint test --template ~/myphint
The short option name for --template
is -x
.
Template variables
Here's what parameters these templates would receive when run:
- docs/docs.twig: classes metadata and docs parameters
- tests/test.twig: class metadata and test parameters
- Everything else: init parameters
Metadata
- The
docs
andtest
commands read and use source files metadata. - The
docs.twig
template recieves metadata collection of all classes at once. - The
test.twig
template recieves metadata unit of one class at a time.
Class metadata
Example metadata for Abc\Dummy above:
[ 'namespace' => 'Abc', 'classFqcn' => 'Abc\\Dummy', 'classPath' => '/home/user/projects/src/Dummy.php', 'name' => 'Dummy', 'className' => 'Dummy', 'isTrait' => false, 'isAbstract' => false, 'isInterface' => false, 'newable' => true, 'title' => 'This is dummy class.', 'texts' => [ 'It does nothing as of now.', 'Maybe you could fix it?', ], 'methods' => [ 'alpha' => [ 'name' => 'alpha', 'inClass' => 'Abc\\Dummy', 'isStatic' => false, 'isFinal' => false, 'isPublic' => true, 'isAbstract' => false, 'maybeMagic' => false, 'title' => 'Alpha beta.', 'texts' => [ 'Example:', '<code>', '$dummy = new Dummy;', '$dummy->alpha(\'john\', true);', '// \'...\'', '</code>', ], 'return' => 'string|null', 'params' => [ 'string $name', 'bool $flag', ], ], // more methods ... ], ];
Todo
Including but not limited to:
- README.md/Docs generator
- Test files generator
- Support user templates
- Test stubs for new methods
License
© 2017-2020, Jitendra Adhikari | MIT
Credits
This library is release managed by please.