What is the best way to create a extension for Yii2?
How to register the extension with the application and how to organize views, controllers and models within the extension?
You can follow each step below to help you set-up your first Yii2 extension:
1. Github setup
Create a new github repo and make sure to follow the naming conventions for yii2-extensions like this:
ourcompany being our github-scope and ourextension the name of our extension.
2. Local project setup
Create a local folder where you will develop the extension. First create a file composer.json. This folder should not be in the vendor-folder of an existing project! It won't work any other way, except to declare a namespaces within autoload.php of surrounding project manually.
The most important things to remember:
- The dependencies (usually the Yii2-framework)
- Autoload-property which declares the namespace for package. This will later be used by yiis-autoloader to find classes.
After that, run composer update this will create the vendor folder containing all referenced libraries.
Here is an example of composer: https://github.com/asinfotrack/yii2-toolbox/blob/master/composer.json
Pay special attention to the autoload block at the end of the file! In this case autoloader that asinfotrack/yii2/toolbox will be mapped to the root-folder of the project. Folder models with class in your project root should have the namespace asinfotrack/yii2/toolbox/models.
The next to create .gitignore-file. Exclude the vendor-folder and all IDE files.
Also an example of the same extension mentioned above. Simply copy/paste it: https://github.com/asinfotrack/yii2-toolbox/blob/master/.gitignore
Now initialize the git-repo, simply navigate to directory and execute the command git init. To add all files and commit for the first time, execute git add -A and git commit -m "message here". Now you are ready to push repo to github.
Need to set the remote of repo to github. This is done with the following command:
git remote add origin https://github.com/ouraccount/ourrepo.git
Also make sure that the following config vars are set correctly:
git config user.email git config user.name
The email should match with your github-account email. If you want to change the values, simply append them to the commands above. Like below:
git config user.email "firstname.lastname@example.org"
Now we need to push the extension to github:
git push origin master
For other users to be able to reference our extension within their projects, we need to register it with packagist.org.
Create an account and submit extension as explained here: https://packagist.org/packages/submit
4. Connecting packagist and github
Packagist mirrors repo for further distribution. Enabling the Packagist service hook ensures that your package will always be updated instantly when you push to GitHub.
Go to the settings of github-repo and navigate to Webhooks & Services. Then add a new hook for packagist. This is supported natively by github. Find the packagist-hook in the dropdown.
We need to provide packagist-API-Token which we can find on the top of account-page when logged into packagist.org. Everything is documented very well here:
That's it! When performing a new commit to github, it will be mirrored automatically to packagist. With a few minutes delay we will receive the updated version of our extension when we execute composer update.
At first all of this might look intimidating and complicated, but actually it's pretty straight forward.