diff --git a/.gitignore b/.gitignore index ff7bf5c..ceb4d7e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,17 +1,5 @@ -nbproject -._* -.~lock.* -.buildpath -.DS_Store -.idea -.project -.settings +.vagrant/ vendor/ -public/vendor/ config/development.config.php -config/autoload/local.php -config/autoload/*.local.php -!public/vendor/README.md data/cache/* !data/cache/.gitkeep -.vagrant diff --git a/CONDUCT.md b/CONDUCT.md new file mode 100644 index 0000000..c663d2b --- /dev/null +++ b/CONDUCT.md @@ -0,0 +1,43 @@ +# Contributor Code of Conduct + +The Zend Framework project adheres to [The Code Manifesto](http://codemanifesto.com) +as its guidelines for contributor interactions. + +## The Code Manifesto + +We want to work in an ecosystem that empowers developers to reach their +potential — one that encourages growth and effective collaboration. A space that +is safe for all. + +A space such as this benefits everyone that participates in it. It encourages +new developers to enter our field. It is through discussion and collaboration +that we grow, and through growth that we improve. + +In the effort to create such a place, we hold to these values: + +1. **Discrimination limits us.** This includes discrimination on the basis of + race, gender, sexual orientation, gender identity, age, nationality, technology + and any other arbitrary exclusion of a group of people. +2. **Boundaries honor us.** Your comfort levels are not everyone’s comfort + levels. Remember that, and if brought to your attention, heed it. +3. **We are our biggest assets.** None of us were born masters of our trade. + Each of us has been helped along the way. Return that favor, when and where + you can. +4. **We are resources for the future.** As an extension of #3, share what you + know. Make yourself a resource to help those that come after you. +5. **Respect defines us.** Treat others as you wish to be treated. Make your + discussions, criticisms and debates from a position of respectfulness. Ask + yourself, is it true? Is it necessary? Is it constructive? Anything less is + unacceptable. +6. **Reactions require grace.** Angry responses are valid, but abusive language + and vindictive actions are toxic. When something happens that offends you, + handle it assertively, but be respectful. Escalate reasonably, and try to + allow the offender an opportunity to explain themselves, and possibly correct + the issue. +7. **Opinions are just that: opinions.** Each and every one of us, due to our + background and upbringing, have varying opinions. The fact of the matter, is + that is perfectly acceptable. Remember this: if you respect your own + opinions, you should respect the opinions of others. +8. **To err is human.** You might not intend it, but mistakes do happen and + contribute to build experience. Tolerate honest mistakes, and don't hesitate + to apologize if you make one yourself. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7d8743..3617ffc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,25 +50,31 @@ First, use [Composer](https://getcomposer.org) to install all dependencies: $ composer install ``` -To run tests, use the PHPUnit executable installed by Composer: +To run tests: ```console -$ ./vendor/bin/phpunit +$ composer test ``` ## CODING STANDARDS -While Apigility uses Zend Framework 2 coding standards, in practice, we check -standards using [php-cs-fixer](https://github.com/fabpot/PHP-CS-Fixer) (which is -installed via Composer with other dependencies). To check for CS issues: +While Apigility uses Zend Framework 2 coding standards, in practice, we verify +against [PSR-2](http://www.php-fig.org/psr/psr-2/). To check for CS issues: ```console -$ ./vendor/bin/php-cs-fixer fix . --dry-run +$ composer cs-check ``` -This will report CS issues. Alternately, you can have the tool fix them for you -by omitting the `--dry-run` switch: +This will report CS issues. Alternately, you can have most errors automatically +fixed as well: ```console -$ ./vendor/bin/php-cs-fixer fix . +$ composer cs-fix ``` + +After running `composer cs-fix`, be sure to add and commit any files that were +updated, after first verifying that the changes do not break tests. + +## Conduct + +Please see our [CONDUCT.md](CONDUCT.md) to understand expected behavior when interacting with others in the project. diff --git a/Dockerfile b/Dockerfile index 39b054f..471a77d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,22 +1,36 @@ -FROM php:5.6-apache +# +# Use this dockerfile to run apigility. +# +# Start the server using docker-compose: +# +# docker-compose build +# docker-compose up +# +# You can install dependencies via the container: +# +# docker-compose run apigility composer install +# +# You can manipulate dev mode from the container: +# +# docker-compose run apigility composer development-enable +# docker-compose run apigility composer development-disable +# docker-compose run apigility composer development-status +# +# OR use plain old docker +# +# docker build -f Dockerfile-dev -t apigility . +# docker run -it -p "8080:80" -v $PWD:/var/www apigility +# +FROM php:7.0-apache RUN apt-get update \ - && apt-get install git zlib1g-dev nano -y --no-install-recommends \ - && rm -r /var/lib/apt/lists/* \ + && apt-get install -y git zlib1g-dev \ && docker-php-ext-install zip \ - && curl -sS https://getcomposer.org/installer \ - | php -- --install-dir=/usr/local/bin --filename=composer \ && a2enmod rewrite \ && sed -i 's!/var/www/html!/var/www/public!g' /etc/apache2/apache2.conf \ - && echo "AllowEncodedSlashes On" >> /etc/apache2/apache2.conf \ && mv /var/www/html /var/www/public \ - && cp /usr/src/php/php.ini-production /usr/local/etc/php/php.ini \ - && printf '[Date]\ndate.timezone=UTC' > /usr/local/etc/php/conf.d/timezone.ini + && curl -sS https://getcomposer.org/installer \ + | php -- --install-dir=/usr/local/bin --filename=composer \ + && echo "AllowEncodedSlashes On" >> /etc/apache2/apache2.conf WORKDIR /var/www - -COPY . . - -RUN chown www-data.www-data /var/www/data/cache \ - && composer install - diff --git a/Dockerfile-dev b/Dockerfile-dev deleted file mode 100644 index c0da363..0000000 --- a/Dockerfile-dev +++ /dev/null @@ -1,40 +0,0 @@ -# -# Use this dockerfile to run apigility in dev mode. -# -# Start the dev server using docker-compose: -# -# docker-compose build -# docker-compose up -# -# OR use plain old docker -# -# docker build -f Dockerfile-dev -t apigility-dev . -# docker run -it -p "8080:80" -v $PWD:/var/www apigility-dev -# -FROM php:5.6-apache - -RUN apt-get update \ - && apt-get install git zlib1g-dev nano -y --no-install-recommends \ - && rm -r /var/lib/apt/lists/* \ - && docker-php-ext-install zip \ - && curl -sS https://getcomposer.org/installer \ - | php -- --install-dir=/usr/local/bin --filename=composer \ - && a2enmod rewrite \ - && sed -i 's!/var/www/html!/var/www/public!g' /etc/apache2/apache2.conf \ - && echo "AllowEncodedSlashes On" >> /etc/apache2/apache2.conf \ - && mv /var/www/html /var/www/public \ - && cp /usr/src/php/php.ini-production /usr/local/etc/php/php.ini \ - && printf '[Date]\ndate.timezone=UTC' > /usr/local/etc/php/conf.d/timezone.ini - -WORKDIR /var/www -### END OF Dockerfile copy - -VOLUME /var/www - -RUN cp /usr/src/php/php.ini-development /usr/local/etc/php/php.ini \ - && sed -i 's/;always_populate_raw_post_data/always_populate_raw_post_data/g' /usr/local/etc/php/php.ini - -CMD composer install \ - && php public/index.php development enable \ - && php -S 0.0.0.0:80 -t public public/index.php - diff --git a/LICENSE.txt b/LICENSE.md similarity index 59% rename from LICENSE.txt rename to LICENSE.md index 7373d0e..f75bf39 100644 --- a/LICENSE.txt +++ b/LICENSE.md @@ -1,19 +1,19 @@ -Copyright (c) 2013, Zend Technologies USA, Inc. +Copyright (c) 2013 - 2016, Zend Technologies USA, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. +- Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. +- Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. - * Neither the name of Zend Technologies USA, Inc. nor the names of its - contributors may be used to endorse or promote products derived from this - software without specific prior written permission. +- Neither the name of Zend Technologies USA, Inc. nor the names of its + contributors may be used to endorse or promote products derived from this + software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED diff --git a/README.md b/README.md index 23071c8..26e6467 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ has distribution tarballs and zipballs available. Untar it: ```bash -tar xzf zf-apigility-skeleton-{version}.tgz +$ tar xzf zf-apigility-skeleton-{version}.tgz ``` (Where `{version}` is the version you downloaded.) @@ -26,7 +26,7 @@ tar xzf zf-apigility-skeleton-{version}.tgz Or unzip, if you chose the zipball: ```bash -unzip zf-apigility-skeleton-{version}.zip +$ unzip zf-apigility-skeleton-{version}.zip ``` (Where `{version}` is the version you downloaded.) @@ -34,11 +34,11 @@ unzip zf-apigility-skeleton-{version}.zip ### Via Composer (create-project) You can use the `create-project` command from [Composer](http://getcomposer.org/) -to create the project in one go (you need to install [composer.phar](https://getcomposer.org/doc/00-intro.md#downloading-the-composer-executable)): +to create the project in one go (you need to install [composer](https://getcomposer.org/doc/00-intro.md#downloading-the-composer-executable)): ```bash -curl -s https://getcomposer.org/installer | php -- -php composer.phar create-project -sdev zfcampus/zf-apigility-skeleton path/to/install +$ curl -s https://getcomposer.org/installer | php -- --filename=composer +$ composer create-project -sdev zfcampus/zf-apigility-skeleton path/to/install ``` ### Via Git (clone) @@ -46,15 +46,15 @@ php composer.phar create-project -sdev zfcampus/zf-apigility-skeleton path/to/in First, clone the repository: ```bash -git clone https://github.com/zfcampus/zf-apigility-skeleton.git # optionally, specify the directory in which to clone -cd path/to/install +# git clone https://github.com/zfcampus/zf-apigility-skeleton.git # optionally, specify the directory in which to clone +$ cd path/to/install ``` At this point, you need to use [Composer](https://getcomposer.org/) to install dependencies. Assuming you already have Composer: ```bash -composer.phar install +$ composer install ``` ### All methods @@ -70,14 +70,16 @@ Now, fire it up! Do one of the following: - Create a vhost in your web server that points the DocumentRoot to the `public/` directory of the project -- Fire up the built-in web server in PHP (5.4.8+) (**note**: do not use this for +- Fire up the built-in web server in PHP(**note**: do not use this for production!) In the latter case, do the following: ```bash -cd path/to/install -php -S 0.0.0.0:8080 -ddisplay_errors=0 -t public public/index.php +$ cd path/to/install +$ php -S 0.0.0.0:8080 -ddisplay_errors=0 -t public public/index.php +# OR use the composer alias: +$ composer serve ``` You can then visit the site at http://localhost:8080/ - which will bring up a @@ -97,7 +99,7 @@ API uses these characters for a number of service endpoints. As such, if you wis Admin UI and/or Admin API with Apache, you will need to configure your Apache vhost/project to allow encoded slashes: -```apache +```apacheconf AllowEncodedSlashes On ``` @@ -148,54 +150,113 @@ server first, or if you know how, you can reconfigure the ports in Vagrantfile. Assuming you have Vagrant installed and assuming you have no port conflicts, you can bring up the Vagrant machine with the standard `up` command: -``` -vagrant up +```bash +$ vagrant up ``` When the machine comes up, you can ssh to it with the standard ssh forward agent: +```bash +$ vagrant ssh ``` -vagrant ssh -``` -The web root is inside the shared directory, which is at `/vagrant`. Once you've ssh'd into the box, you need to cd: +The web root is inside the shared directory, which is at `/var/www`; this is +also the home directory for the vagrant issue, which will be the initial +directory you land in once you connect via SSH. + +The image installs composer during provisioning, meaning you can use it to +install and update dependencies: +```bash +# Install dependencies: +$ vagrant ssh -c 'composer install' +# Update dependencies: +$ vagrant ssh -c 'composer update' ``` -cd /vagrant + +You can also manipulate development mode: + +```bash +$ vagrant ssh -c 'composer development-enable' +$ vagrant ssh -c 'composer development-disable' +$ vagrant ssh -c 'composer development-status' ``` +> #### Vagrant and VirtualBox +> +> The vagrant image is based on ubuntu/xenial64. If you are using VirtualBox as +> a provider, you will need: +> +> - Vagrant 1.8.5 or later +> - VirtualBox 5.0.26 or later + For vagrant documentation, please refer to [vagrantup.com](https://www.vagrantup.com/) ### Docker -If you develop or deploy using Docker, we provide both development and production configuration for -you. - -#### Development +If you develop or deploy using Docker, we provide configuration for you. Prepare your development environment using [docker compose](https://docs.docker.com/compose/install/): + ```bash -git clone https://github.com/zfcampus/zf-apigility-skeleton +$ git clone https://github.com/zfcampus/zf-apigility-skeleton +$ cd zf-apigility-skeleton +$ docker-compose build +# Install dependencies via composer, if you haven't already: +$ docker-compose run apigility composer install +# Enable development mode: +$ docker-compose run apigility composer development-enable +``` + +Start the container: + +```bash +$ docker-compose up +``` + +Access Apigility from `http://localhost:8080/` or `http://:8080/` if on Windows or Mac. + +You may also use the provided `Dockerfile` directly if desired. -cd zf-apigility-skeleton +Once installed, you can use the container to update dependencies: -docker-compose build +```bash +$ docker-compose run apigility composer update ``` -Start the development environment: +Or to manipulate development mode: + ```bash -docker-compose up +$ docker-compose run apigility composer development-enable +$ docker-compose run apigility composer development-disable +$ docker-compose run apigility composer development-status ``` -Access your editor from `http://localhost:8080/` or `http://:8080/` if on Windows or Mac. -#### Production +QA Tools +-------- + +The skeleton does not come with any QA tooling by default, but does ship with +configuration for each of: + +- [phpcs](https://github.com/squizlabs/php_codesniffer) +- [phpunit](https://phpunit.de) + +Additionally, it comes with some basic tests for the shipped +`Application\Controller\IndexController`. + +If you want to add these QA tools, execute the following: -Use the included [Dockerfile](https://docs.docker.com/reference/builder/) to build an [Apache](http://httpd.apache.org/) container: ```bash -docker build -t apighost . +$ composer require --dev phpunit/phpunit squizlabs/php_codesniffer zendframework/zend-test ``` -Test your container: +We provide aliases for each of these tools in the Composer configuration: + ```bash -docker run -it -p "80:80" apighost +# Run CS checks: +$ composer cs-check +# Fix CS errors: +$ composer cs-fix +# Run PHPUnit tests: +$ composer test ``` diff --git a/Vagrantfile b/Vagrantfile index e42c709..12866f8 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -1,17 +1,62 @@ -dir = File.dirname(File.expand_path(__FILE__)) +# -*- mode: ruby -*- +# vi: set ft=ruby : -require 'yaml' -require "#{dir}/puphpet/ruby/deep_merge.rb" +VAGRANTFILE_API_VERSION = '2' -configValues = YAML.load_file("#{dir}/puphpet/config.yaml") +@script = <