This repo contains tools to set up a development environment for Yii3 packages. It allows working on separate packages and test the result in other packages at the same time. Could be used for third party packages as well.
If you prefer manual install, you need:
- GNU/Linux or Windows with bash
- PHP 8.0 or higher
- Composer installed and
available as
composer
on the command line
If you prefer Vagrant, you only need to install Vagrant and VirtualBox, because our Vagrant environment already contains Ubuntu, PHP and Composer. See our Vagrant documentation for details.
If you prefer Docker, you only need to install Docker.
See our Docker documentation for details.
git clone https://github.com/yiisoft/yii-dev-tool
cd yii-dev-tool
composer install
./yii-dev install
The above command will clone all Yii3 packages and run composer install
in them.
You may select packages by providing a second argument:
./yii-dev install di,rbac,yii-cycle,view
Note: In case you are using PhpStorm, run
ide
command once to configure the project directories for installed packages to avoid infinite indexing cycle.
To upgrade yii-dev-tool to the latest version, run the following commands:
cd yii-dev-tool
git pull
composer update
To customize the configuration of yii-dev-tool, create your local configuration packages.local.php
using file packages.local.php.example
as example. In this file you will find examples of all available
configuration options.
Some commands such as github/protect-branch
, github/settings
, release/make
require a GitHub auth token. Therefore, you need to create a personal access token on GitHub.
Then save it in config/github.token
file.
Suppose we want to work on three interdependent packages:
- yiisoft/demo
- yiisoft/view
- yiisoft/i18n
Package demo depends on package view, and package view depends on package i18n.
Suppose we want to add new features to package i18n, and then use them in package view. After that, we will need to run the tests in package demo and make sure that everything works correctly.
Go to the page of each repository and click the "Fork" button:
Suppose my nickname on Github is "samdark". Then I will get three forks:
- samdark/demo
- samdark/view
- samdark/i18n
For your nickname you will get other fork names.
Now install yii-dev-tool:
git clone https://github.com/yiisoft/yii-dev-tool
cd yii-dev-tool
composer install
In order for yii-dev-tool to use our forks, they must be configured.
It is possible to specify the owner for all packages in the owner-packages.php file
return 'samdark';
Or create your configuration:
cd yii-dev-tool
cp packages.local.php.example packages.local.php
Specify the forks in config packages.local.php
:
$packages = [
'demo' => 'samdark/demo',
'view' => 'samdark/view',
'i18n' => 'samdark/i18n',
];
See example.
In order to work with Github via SSH, you have to add your public SSH key to Github account. Add key if you have not done it before.
Now install the packages:
cd yii-dev-tool
./yii-dev install demo,view,i18n
This command clones the fork repositories from GitHub to the local directory yii-dev-tool/dev/
,
sets upstream
for them and executes composer install
in each package. Then symlinks will be created:
- yii-dev-tool/dev/demo/vendor/yiisoft/view -> yii-dev-tool/dev/view
- yii-dev-tool/dev/view/vendor/yiisoft/i18n -> yii-dev-tool/dev/i18n
Due to these symlinks, changes in packages will immediately affect the operation of packages that depend on them. It is very convenient for development.
Create a new feature-x branch in the repositories:
cd yii-dev-tool
./yii-dev git/checkout feature-x demo,view,i18n
Now make the necessary changes to the code of package i18n in folder yii-dev-tool/dev/i18n
.
Next, make changes to the code of package view in folder yii-dev-tool/dev/view
.
And, finally, change package demo in folder yii-dev-tool/dev/demo
.
Make sure the tests pass. For instance, package view tests can be run with the following command:
cd yii-dev-tool/dev/view
./vendor/bin/phpunit
Commit the changes:
cd yii-dev-tool
./yii-dev git/commit "Add feature X" demo,view,i18n
Push the new code to remote repositories:
cd yii-dev-tool
./yii-dev git/push demo,view,i18n
Go to the pages of the original repositories and create a PR in each:
Note: Don't create PR from master directly, instead create a new branch.
That's all. We developed new functionality and submitted it for review 🙂 Of course, the steps will be slightly different for different tasks and configurations.
Remember that yii-dev-tool contains many other commands:
Command | Aliases | Description |
---|---|---|
changelog/add | Adds a changelog entry into CHANGELOG.md into under development section. |
|
exec | e | Executes the specified console command in each package. |
composer/update | cu | Update composer dependencies in packages. |
git/checkout | checkout | Creates, if not exists, and checkout a git branch. |
git/clone | clone | Package repositories cloning. |
git/commit | commit | Add and commit changes into each package repository. |
git/pull | pull | Pull changes from package repositories. |
git/push | push | Push changes into package repositories. |
git/status | status, s | Show git status of packages. |
git/pr/create | pr | Create a pull request at GitHub. |
github/forks | forks | Create forks of repositories |
github/sync | sync | Sync forks from upstream repositories |
github/settings | - | Change settings of a GitHub repository. |
list | l | List enabled packages. |
install | i | Clone packages repositories and install composer dependencies. |
update | u | Pull changes from packages repositories and update composer dependencies. |
lint | - | Check packages according to PSR-12 standard. |
release/make | - | Make a package release. |
replicate/files | - | Copy files specified in config/replicate/files.php into each package. |
replicate/composer-config | - | Merge config/replicate/composer.json into composer.json of each package. |
replicate/copy-file | - | Copy file into each package. |
test | t | Test packages. |
enable | - | Enable packages. |
disable | - | Disable packages. |
switch | - | Enable specified packages and disable others. |
If you encounter any problems, create an issue – and we'll try to help you.