{"id":20556631,"url":"https://github.com/clevertech/yiiboilerplate","last_synced_at":"2025-04-06T03:09:37.638Z","repository":{"id":145694465,"uuid":"5290963","full_name":"clevertech/YiiBoilerplate","owner":"clevertech","description":null,"archived":false,"fork":false,"pushed_at":"2014-06-09T16:25:59.000Z","size":15680,"stargazers_count":361,"open_issues_count":5,"forks_count":147,"subscribers_count":86,"default_branch":"master","last_synced_at":"2025-03-30T01:12:16.910Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clevertech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-08-03T22:01:42.000Z","updated_at":"2025-03-15T20:58:27.000Z","dependencies_parsed_at":"2023-03-27T12:35:19.454Z","dependency_job_id":null,"html_url":"https://github.com/clevertech/YiiBoilerplate","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2FYiiBoilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2FYiiBoilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2FYiiBoilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2FYiiBoilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clevertech","download_url":"https://codeload.github.com/clevertech/YiiBoilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T03:30:39.284Z","updated_at":"2025-04-06T03:09:37.616Z","avatar_url":"https://github.com/clevertech.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# YiiBoilerplate\nStructure for enterprise-grade websites for Yii framework. Already thought-out.\n\nWhile making websites with [Yii framework][yii] for medium-sized businesses over and over again, we adopted a standard way of structuring the project over time.\nIt was initially based on the following premises:\n\n1. Separate public (\"frontend\") and administrator's (\"backend\") sides to different domains for security purposes.\n2. Have an application configuration modular, so we can have parts of it committed to VCS repository for everyone and parts of it being crafted for every specific developer.\n\nThis two premises have lead to significant changes from the [traditional project structure, described in Yii tutorial][yii-default-structure]. It even affected the terminology, creating two new terms \"entry point\" and \"environment\".\n\nFor quite some time we were building Yii-based websites using this structure and it proved really effective. This article will describe to you the all-new [YiiBoilerplate][yiiboilerplate] with all the new features added in that time.\n\nWe do really hope that you'll benefit from this boilerplate project template.\n\n# Being a Boilerplate\n\nWe must make a note first that YiiBoilerplate is neither a library nor an another framework.\nIt's a *boilerplate*, stuff you use as a starting point for your work.\n\nAs a consequence of this, do not bother thinking about \"updates\" or \"future versions\" of YiiBoilerplate after you started your project over it. Just adapt it to your needs as you wish.\n\n# Requirements\n\n-   **PHP 5.4**.\n    Seriously, even [Debian Stable](http://packages.debian.org/stable/php/php5), notorious for slow library upgrades, has version 5.4 now.\n    Upgrade right now and/or stop using hosting providers with old PHP versions.\n-   Probably, **enabled support for running PHAR archives from console** (it has to be enabled via `php.ini`).\n-   *Optional*: **Java** to be able to run Selenium.\n-   *Optional*: **Virtualbox** and **Vagrant** for the easiest local deploy ever.\n\n# Easiest initial deploy ever\n\n1.  Install [Vagrant][vagrant] (not covered by this article).\n\n2.  Install [Virtualbox][virtualbox] (not covered by this article).\n\n3.  If you have PHP 5.4+ installed already ([and you should have, because it's awesome][php-5.4-changelog]), you've just installed all prequisites for YiiBoilerplate.\n\n4.  Now just clone the YiiBoilerplate repo:\n\n        git clone git@github.com:clevertech/YiiBoilerplate.git \u003cyourprojectname\u003e\n\n5.  Inside cloned directory run and wait for complete:\n\n        vagrant up\n        \n    Vagrant can complain about versions of VirtualBox Guest Additions and Virtualbox itself being different.\n    This is solved by running `vagrant plugin install vagrant-vbguest`, the only non-obvious step you should encounter so far.\n\n6.  You're done. Open up the [http://localhost:8080/](http://localhost:8080/). It's your future frontend. Open up [http://localhost:8081/](http://localhost:8081/). It's your future backend. You can start working.\n    Don't forget to `vagrant halt` the virtual machine before turning off your workstation, virtualbox can fail to shut itself down in time before `kill -9` arrives.\n\n# Manual preparations\n\nConsult the `carcass/vagrant/prepare-precise64.sh` and `carcass/vagrant/setup-app.sh` scripts for example.\n\n# Get a full health report for a project\n\nWe integrated almost everything from the [PHP QA Tools project][phpqatools], over the [Phing build system][phing].\n\nTo get all possible static code analysis reports for your project and the API documentation, just run:\n\n    bin/phing\n\nIt will generate the following reports in the `reports` folder:\n\n* Report of the code style violations in Checkstyle format from [PHP Code Sniffer][phpcs]\n* Code coverage report in Clover format from [PHPUnit][phpunit]\n* Code duplications report in XML from [PHP Copy-Paste Detector][phpcpd]\n* Codebase size report in XML from [PHPLOC][phploc]\n* Various problems report in XML from [PHP Mess Detector][phpmd]\n* Report in XML from [PDepend][pdepend]\n* Two code metrics schematics in SVG from PDepend\n* Code coverage report in HTML format from PHPUnit\n* HTML pages tree with all of your codebase with all above problems highlighted from [PHP Code Browser][phpcb]\n* and, finally, the autogenerated API documentation in HTML from [ApiGen][apigen].\n\nWe believe it'll be sufficient for you to get an idea about the state of your codebase.\nOf course to generate code coverage reports this reporter has to run all unit tests, too, so you get regression testing as a side effect, assuming that your unit tests are really fast.\n\n# Overview\n\nNow, let's delve into internals.\n\nYiiBoilerplate was designed for medium-sized Yii-based web applications of any kind.\nBy \"meduim-sized\" we mean 10 to 100 unique routes.\nAgain, it has a harness to support two-tier test-first development, with [Behat][behat] for end-to-end acceptance tests and [PHPUnit][phpunit] for both pure unit tests and integration tests.\n\nBasically, YiiBoilerplate is a bunch of files and folders you commit to your VCS repo as your \"initial commit\", then start working for real.\nIt consists of a proof-of-concept website, having one-page blank frontend and an admin side with rudimentary UI and a password-based authentication already done.\n\nYou can read the whole \"table of contents\" for the various directories of the YiiBoilerplate in `README.md` files inside that directories.\n\n## Top-level Directories\n\n1.  `backend`\n\n    Backend entry point, expected to be your \"admin side\" of the application.\n\n2.  `bin`\n\n    Binaries for you to use, including `yiic`, `phing`, `phpunit` and such.\n    Note that while most of binaries are Composer-installed, `yiic` and `selenium` launchers are hand-crafted\n    and not supposed to be removed/changed.\n\n3.  `carcass`\n\n    Configuration for various 3rd-party tools used in project harness,\n    including Vagrant stuff and code style definition for CodeSniffer.\n\n4.  `common`\n\n    This folder is structured similarly to the traditional `protected` folder in autogenerated Yii application.\n    You are expected to place the code global to all entry points in `common`.\n    Backend-, frontend-, and console-specific stuff should go to `backend`, `frontend` and `console` dirs, respectively.\n\n5.  `console`\n\n    Console entry point, reachable by `yiic` console runner.\n    Most important stuff here is your migrations, inside `console/migrations` subfolder.\n\n6.  `frontend`\n\n    Frontend entry point, expected to be public side of your application.\n\n7.  `reports`\n\n    All project status reports from various code quality tools will be placed in here. Documentation from APIGen, too.\n    You will not see this directory initially, it's auto-generated when needed.\n\n8.  `tests`\n\n    Your test harness is here. See details in the `README.md` there.\n\n9.  `vendor`\n\n    All third-party dependencies are installed by Composer in here, even Selenium.\n    You will not see this directory initially, it's auto-generated when needed.\n\n## Configuration tree\n\nMost complex part of the YiiBoilerplate application is the configuration, built from set of different parts.\n\nBasically, configuration for backend, console and frontend entry points is being constructed from the following parts, later ones overriding previous ones:\n\n1. Base common config.\n2. Environment-specific common config.\n3. Local overrides for common config.\n4. Base entry point-specific config.\n5. Environment-specific entry point-specific config.\n6. Local overrides for entry-point-specific config.\n\nFor frontend entry point the corresponding files would be:\n\n1. `common/config/overrides/base.php`\n2. `common/config/overrides/environment.php`\n3. `common/config/overrides/local.php`\n4. `frontend/config/overrides/base.php`\n5. `frontend/config/overrides/environment.php`\n6. `frontend/config/overrides/local.php`\n\nLocal overrides and environment overrides can be absent.\n\nYou can trace the resulting tree of `require` calls starting from `frontend/config/main.php` file.\nThat's the file you really use as the configuration file for application.\nIn reality it's just a four-line builder constructing the resulting configuration tree from six different parts specified above.\n\n### Local overrides\n\nLocal overrides are simple. That's the snippets of configuration containing the non-portable parts like database access credentials.\n\n`config/overrides` subdirectory in all of `common`, `frontend`, `console` and `backend` directories contains the `local-example.php` file which you can copy as `local.php` and immediately use.\n\nThese overrides are not to be committed to the repository as they contain the settings specific to each developer's machine.\n\n### Environment overrides\n\nConfiguration snippets for different environments are placed inside `config/environments` directories.\nYou can specify things there like the different database paths, caching mechanisms, some OS-specific parameters, or anything you want.\nTo activate the desired environment, you are expected to copy needed configuration snippet from inside `config/environments` subdir and place it into `config/overrides/` under the name `environment.php`. As it's an obviously mundane and boring to hell task it's automated for you by invoking the following command:\n\n    bin/yiic environment set --id=\u003cenvironmentname\u003e\n\nOf course, each `config/environments` subdirectory in all of entry points should have a configuration snippet named `\u003cenvironmentname\u003e`.\n\nEnvironment overrides are to be committed to the repository as they contain the proven set of settings intended to adapt the application to different working conditions.\n\nNothing forces you to really use this system of environment-specific settings. Configuration builder will happily live without these files.\n\n## Vagrant\n\nYiiBoilerplate includes [Vagrant][vagrant] harness which you can use as you wish.\n`Vagrantfile` is set up to use the default `precise64` box, which is Virtualbox image loaded with blank [Ubuntu 12.04][ubuntu1204].\n\nAs YiiBoilerplate is a rudimentary web application, we prepared a set of scripts to deploy it to Vagrant virtual machine.\nThey are located at `carcass/vagrant` subdirectory.\nTwo scripts, which are used as provisioning scripts for Vagrant, can be used as an examples of automatic deploy of the YiiBoilerplate application to any *nix-based system:\n\n* `prepare-precise64.sh` is a script to install the required tech stack for common database-backed web application to Ubuntu 12.04: PHP 5.4, apache, mysql, git etc. and create the database.\n* `setup-app.sh` is a script to install the application to prepared system: generate configs, required runtime directories, install dependencies.\n\nYou are encouraged to read through them yourself, they're not so hard to comprehend.\n\nNote that in default installation after each `vagrant provision` call you will have to wait until all three `apt-get update` calls finish. This is time-consuming.\nTo relieve yourself from this burden, you can safely pack the machine created by initial `vagrant up` to the custom Vagrant box and reference this box instead of generic `precise64`.\nThis way you'll safely remove `prepare-precise64.sh` from the provisioning scripts list in `Vagrantfile`.\n\nIf you did not understand a word from the preceding paragraph, consult the [documentation about `vagrant box repackage`](http://docs.vagrantup.com/v2/cli/box.html) command and the [documentation about provisioning](http://docs.vagrantup.com/v2/provisioning/index.html) on Vagrant site.\n\n## Composer\n\nAll 3rd-party components of YiiBoilerplate, including Yii itself, are managed by the [Composer][composer].\nYou get [Behat][behat]+[Mink][mink]+[MinkExtension][mink-extension], [PHPUnit][phpunit], full stack of [PHP Quality Assurance toolchain][phpqatools], [Phing][phing], [ApiGen][apigen], [Yii][yii] and [YiiBooster][yii-booster] as your dependencies. Even [Selenium][selenium] was packaged into Composer so it's being installed, too.\n\nUsing Composer greatly reduces the size of your application codebase checked into the repository.\nTo ensure that everyone in your team gets exactly the same versions of the 3rd-party software,\nComposer generates a special file called [`composer.lock`][composer.lock], which you commit to the repository instead of the whole `vendor` folder, and the presense of this file will indicate to Composer what exact versions of software to maintain in a given codebase.\nYiiBoilerplate repo contains such a file so you can be reasonably sure that at least its developers managed to run boilerplate application using the set of dependencies specified in there.\n\n`composer.json` was tweaked so you will get all executables inside `bin` subdirectory.\n\n## Phing\n\nMost possibly you'll need the build system for your application, so we included the PHP-based one, namely, [Phing][phing].\n\nBuild file included in YiiBoilerplate contains the targets allowing you to generate the comprehensive set of reports about the health of your application.\n\nResults of running the default target by issuing `bin/phing` from root of codebase was already described before.\n\nPlease note that the set of source directories for each different tool being run by Phing is specified in separate build file `carcass/filesets.xml`.\nWe're sorry, but various directories excluded from analysis you have to hack inside the main build file, in case you'll change the structure of a project.\n\n## Yiic\n\n[Usual console runner from Yii][yiic] was moved to `bin` subdirectory. As Composer is configured to install executables into the same directory, it was done to prevent you from using the default console runner instead of the one built-in to YiiBoilerplate, which you have total control over.\n\nWhole `console` subdirectory is for this console entry point to the application.\n\nSo, to run any console command built-in to Yii or defined by you in `console/commands`, you have to run `bin/yiic \u003ccommand\u003e` from root of codebase (instead of more short `./yiic`).\n\nWe have found this an acceptable trade-off.\n\n## Behat\n\nAs an acceptance tests driver we included [Behat][behat]+[Mink][mink]+[MinkExtension][mink-extension] combo over the [Selenium2][selenium-driver] driver.\n\nThis gives you arguably the best PHP-based acceptance testing solution out there.\nGherkin syntax allows you and your QA team and perhaps even your client to specify the desired behavior of the application in human language, which is the clear win.\nSelenium uses real browser to manipulate the web GUI of your application, and does this *insanely* fast, so you will not need to cope with any of shortcomings of the headless browsers like [phantomJS][phantomjs] or [Zombie][zombie].\n\nAll required configuration was already done.\n`behat.yml` config file is placed into the root of codebase for your convenience, so you'll be able to run Behat without the hassle of specifying the path to config file in command line arguments.\nYou need to do only one thing: place a config called `behat-local.yml` into the root of codebase, in which you specify the only non-portable setting: base URL for Mink to be able to connect to your web application.\nIf you run Vagrant virtual machine, provisioning script will place the `behat-local.yml` pointing to its URLs automatically. So you can look at `carcass/vagrant/behat-local.yml` file to understand what is needed from you.\n\nIf you use the default setup based on Selenium, you have to run the `bin/selenium` helper script\nwhich just launches Selenium, taking up one console terminal.\n\nAll of your specs related to frontend are expected to be placed into `tests/specs/frontend`.\nYou run them all using the simple invocation `bin/behat -p frontend`.\n\nAll of your specs related to backend are expected to be placed into `tests/specs/backend`.\nYou run them all using the simple invocation `bin/behat -p backend`.\n\nBoth sets of the specs use the same context class located in the `tests/specs/contexts/FeatureContext.php`. All of your test steps definitions should be placed there.\nPlease note that a single `FeatureContext` class is just a starting point, nothing prevents you from structuring your acceptance test harness as you see fit.\n\n## PHPUnit\n\nFor unit testing we included the [PHPUnit][phpunit] library as the Composer dependency.\nIts executable is in `bin`, along with all other executables,\nand by default you run all unit tests at once, as they have to be crazy fast anyway.\nIts `phpunit.xml` config file is placed in the root of codebase for your convenience, so you'll be able to run PHPUnit as `bin/phpunit` and be freed from specifying the path to config file.\n\nConfig file we included in YiiBoilerplate does not have any code coverage setup definitions.\nTo get a code coverage you are expected to use Phing target named `coverage` as follows: `bin/phing coverage`, which specifies code coverage settings using command line switches.\n\nOur intention was to make a harness to support *only pure isolated unit tests*, so you get totally clean environment inside test cases.\nIn case where you need the integration test, we prepared the bootstrap script for PHPUnit which does the common initialization of YiiBoilerplate application as defined in `common/bootstrap.php` and does some tricks the same way `yiit.php` script does. This bootstrap script is essentially the fourth entry point to your application.\n\nSo when you run:\n\n    bin/phpunit --bootstrap carcass/phpunit.bootstrap.php\n\nYou run your test cases in the environment where the Yii class is defined and all usual setup is done so you can freely instantiate WebApplication instances as you see fit and using any configuration you want in your tests.\n\n## YiiBooster\n\nFor backend side of the application, we included our other library, [YiiBooster][yii-booster] as a Composer dependency, and made the configuration required to attach it.\n\nSo, in effect, you'll get the total power of YiiBooster to make the UI of your backend.\nYou are expected to skim through the [YiiBooster documentation][yii-booster-docs] to learn what widgets you get from this toolkit.\n\nFrontend, in contrast, is completely blank [HTML5Boilerplate][html5-boilerplate], because judging from our own experience, public side of the application is unique for every project anyway, so default styles from [Twitter Bootstrap][bootstrap] will not find any place there.\n\n\n# License\n\nAll of the code by default is licensed by [BSD license][bsd-license], as all opensource work from Clevertech.\n\nHowever, as you most possibly will change everything inside the codebase over time, you can probably treat the code as being in public domain. Our terms and intention is that you can adapt anything inside YiiBoilerplate to your needs.\n\n# phpStorm tweaks\n\nTo fully utilize phpStorm's autocompletion feature we have to do some tweaks to instruct it to ignore some files\nfrom 3rd-party libraries.\n\n1.  We use our custom `Yii` class, to utilize the F4 button over the `Yii::app()` invocation\n    and to regain control over this singleton in general.\n    However, this leads to duplicate definitions as far as phpStorm is concerned.\n\n    1.  In `File -\u003e Settings -\u003e PHP` under *Include Path* section find the entry ending in `yiisoft/yii` entry\n        and change it so it will end in `yiisoft/yii/framework`.\n    2.  Similarly change the entry ending in `clevertech/yii-booster` so that it ends in `clevertech/yii-booster/src`.\n    3.  In `File -\u003e Settings -\u003e File Types` under *Ignore files and folders* section\n        append the string `;framework/Yii.php;tests/fakes/Yii.php` verbatim.\n\n2.  Also, Behat distribution shipped with Composer includes the `FeatureContext` class which conflicts with our own.\n    In `File -\u003e Settings -\u003e PHP` under *Include Path* section find the entry ending in `behat/behat` and append `src` to it.\n    This will exclude the tests code from Behat library index.\n\nPlease note that due to the indexing mechanism of phpStorm you will either need to change the PHP include paths each time\nyou make changes in `composer.json` or to disable the auto-reindexing of Composer-installed libraries altogether.\n\nSide note regarding phpStorm usage with Yii-based applications: if you want Yii application components to be accessible\nby hitting F4 over the component name in expressions like `Yii::app()-\u003erequest`, you have to write `@property` doc blocks\nfor your WebApplication class assigning proper class names to the component IDs. It increases human-readability, too.\n\n====\n\n\u003e [![Clevertech](http://clevertech.biz/images/slir/w54-h36-c54:36/images/site/index/home/clevertech-logo.png)](http://www.clevertech.biz)    \nwell-built beautifully designed web applications  \n[www.clevertech.biz](http://www.clevertech.biz)\n\n[yii]: http://www.yiiframework.com/\n[yii-default-structure]: http://www.yiiframework.com/doc/guide/1.1/en/basics.convention#directory\n[yiiboilerplate]: https://github.com/clevertech/YiiBoilerplate\n[uncle-bob-the-screaming-architecture]: http://blog.8thlight.com/uncle-bob/2011/09/30/Screaming-Architecture.html\n[vagrant]: http://docs.vagrantup.com/v2/getting-started/\n[virtualbox]: https://www.virtualbox.org/\n[php-5.4-changelog]: http://www.php.net/manual/en/migration54.new-features.php\n[atdd]: http://guide.agilealliance.org/guide/atdd.html\n[goos]: http://www.growing-object-oriented-software.com/\n[behat]: http://behat.org/\n[phpunit]: http://phpunit.de/\n[gherkin]: http://docs.behat.org/guides/1.gherkin.html\n[phpqatools]: http://phpqatools.org/\n[phing]: http://www.phing.info/\n[phpcs]: http://pear.php.net/PHP_CodeSniffer\n[phpcpd]: http://github.com/sebastianbergmann/phpcpd\n[phploc]: http://github.com/sebastianbergmann/phploc\n[phpmd]: http://phpmd.org/\n[pdepend]: http://pdepend.org/\n[phpcb]: https://github.com/Mayflower/PHP_CodeBrowser\n[apigen]: http://apigen.org/\n[ubuntu1204]: http://releases.ubuntu.com/precise/\n[composer]: http://getcomposer.org/\n[mink]: http://mink.behat.org/\n[mink-extension]: http://extensions.behat.org/mink/\n[yii-booster]: http://yii-booster.clevertech.biz/\n[selenium]: http://docs.seleniumhq.org/\n[composer.lock]: http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file\n[yiic]: http://www.yiiframework.com/doc/guide/1.1/en/topics.console\n[selenium-driver]: https://github.com/Behat/MinkSelenium2Driver\n[phantomjs]: http://phantomjs.org/\n[zombie]: http://zombie.labnotes.org/\n[yii-booster-docs]: http://yii-booster.clevertech.biz/widgets/\n[html5-boilerplate]: http://html5boilerplate.com/\n[bootstrap]: http://getbootstrap.com/\n[bsd-license]: http://opensource.org/licenses/BSD-2-Clause\n[yii-boilerplate-issues]: https://github.com/clevertech/YiiBoilerplate/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclevertech%2Fyiiboilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclevertech%2Fyiiboilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclevertech%2Fyiiboilerplate/lists"}