diff --git a/README.md b/README.md index fe3c152..3430a36 100644 --- a/README.md +++ b/README.md @@ -2,43 +2,26 @@ -

Yii 2 Basic Project Template

+

Yii 2 REST API Project Template


-Yii 2 Basic Project Template is a skeleton [Yii 2](http://www.yiiframework.com/) application best for -rapidly creating small projects. +Yii 2 REST API Project Template is a skeleton [Yii 2](http://www.yiiframework.com/) application best for +rapidly creating small rest api projects. -The template contains the basic features including user login/logout and a contact page. +The template contains the basic features including user join/login api. It includes all commonly used configurations that would allow you to focus on adding new features to your application. -[![Latest Stable Version](https://img.shields.io/packagist/v/yiisoft/yii2-app-basic.svg)](https://packagist.org/packages/yiisoft/yii2-app-basic) -[![Total Downloads](https://img.shields.io/packagist/dt/yiisoft/yii2-app-basic.svg)](https://packagist.org/packages/yiisoft/yii2-app-basic) -[![Build Status](https://travis-ci.com/yiisoft/yii2-app-basic.svg?branch=master)](https://travis-ci.com/yiisoft/yii2-app-basic) - -DIRECTORY STRUCTURE -------------------- - - assets/ contains assets definition - commands/ contains console commands (controllers) - config/ contains application configurations - controllers/ contains Web controller classes - mail/ contains view files for e-mails - models/ contains model classes - runtime/ contains files generated during runtime - tests/ contains various tests for the basic application - vendor/ contains dependent 3rd-party packages - views/ contains view files for the Web application - web/ contains the entry script and Web resources - - +[![Latest Stable Version](https://poser.pugx.org/forecho/yii2-rest-api/v/stable)](https://packagist.org/packages/forecho/yii2-rest-api) +[![Total Downloads](https://poser.pugx.org/forecho/yii2-rest-api/downloads)](https://packagist.org/packages/forecho/yii2-rest-api) +[![Latest Unstable Version](https://poser.pugx.org/forecho/yii2-rest-api/v/unstable)](https://packagist.org/packages/forecho/yii2-rest-api) +[![License](https://poser.pugx.org/forecho/yii2-rest-api/license)](https://packagist.org/packages/forecho/yii2-rest-api) REQUIREMENTS ------------ -The minimum requirement by this project template that your Web server supports PHP 5.6.0. - +The minimum requirement by this project template that your Web server supports PHP 7.2.0. INSTALLATION ------------ @@ -51,34 +34,31 @@ at [getcomposer.org](http://getcomposer.org/doc/00-intro.md#installation-nix). You can then install this project template using the following command: ~~~ -composer create-project --prefer-dist yiisoft/yii2-app-basic basic +composer create-project --prefer-dist forecho/yii2-rest-api +cd +cp .env.example .env ~~~ -Now you should be able to access the application through the following URL, assuming `basic` is the directory +Now you should be able to access the application through the following URL, assuming `rest-api` is the directory directly under the Web root. ~~~ -http://localhost/basic/web/ +http://localhost//web/ ~~~ -### Install from an Archive File - -Extract the archive file downloaded from [yiiframework.com](http://www.yiiframework.com/download/) to -a directory named `basic` that is directly under the Web root. +### Install from GitHub -Set cookie validation key in `config/web.php` file to some random secret string: +Accessing [Use this template](https://github.com/forecho/yii2-rest-api/generate) Create a new repository from yii2-rest-api -```php -'request' => [ - // !!! insert a secret key in the following (if it is empty) - this is required by cookie validation - 'cookieValidationKey' => '', -], +``` +cd +cp .env.example .env ``` You can then access the application through the following URL: ~~~ -http://localhost/basic/web/ +http://localhost//web/ ~~~ @@ -104,130 +84,33 @@ You can then access the application through the following URL: - Minimum required Docker engine version `17.04` for development (see [Performance tuning for volume mounts](https://docs.docker.com/docker-for-mac/osxfs-caching/)) - The default configuration uses a host-volume in your home directory `.docker-composer` for composer caches +Check out the packages +------------ -CONFIGURATION -------------- - -### Database - -Edit the file `config/db.php` with real data, for example: - -```php -return [ - 'class' => 'yii\db\Connection', - 'dsn' => 'mysql:host=localhost;dbname=yii2basic', - 'username' => 'root', - 'password' => '1234', - 'charset' => 'utf8', -]; -``` - -**NOTES:** -- Yii won't create the database for you, this has to be done manually before you can access it. -- Check and edit the other files in the `config/` directory to customize your application as required. -- Refer to the README in the `tests` directory for information specific to basic application tests. - - -TESTING -------- - -Tests are located in `tests` directory. They are developed with [Codeception PHP Testing Framework](http://codeception.com/). -By default there are 3 test suites: - -- `unit` -- `functional` -- `acceptance` - -Tests can be executed by running - -``` -vendor/bin/codecept run -``` - -The command above will execute unit and functional tests. Unit tests are testing the system components, while functional -tests are for testing user interaction. Acceptance tests are disabled by default as they require additional setup since -they perform testing in real browser. - - -### Running acceptance tests - -To execute acceptance tests do the following: - -1. Rename `tests/acceptance.suite.yml.example` to `tests/acceptance.suite.yml` to enable suite configuration - -2. Replace `codeception/base` package in `composer.json` with `codeception/codeception` to install full featured - version of Codeception - -3. Update dependencies with Composer - - ``` - composer update - ``` - -4. Download [Selenium Server](http://www.seleniumhq.org/download/) and launch it: - - ``` - java -jar ~/selenium-server-standalone-x.xx.x.jar - ``` - - In case of using Selenium Server 3.0 with Firefox browser since v48 or Google Chrome since v53 you must download [GeckoDriver](https://github.com/mozilla/geckodriver/releases) or [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/downloads) and launch Selenium with it: - - ``` - # for Firefox - java -jar -Dwebdriver.gecko.driver=~/geckodriver ~/selenium-server-standalone-3.xx.x.jar - - # for Google Chrome - java -jar -Dwebdriver.chrome.driver=~/chromedriver ~/selenium-server-standalone-3.xx.x.jar - ``` - - As an alternative way you can use already configured Docker container with older versions of Selenium and Firefox: - - ``` - docker run --net=host selenium/standalone-firefox:2.53.0 - ``` - -5. (Optional) Create `yii2_basic_tests` database and update it by applying migrations if you have them. - - ``` - tests/bin/yii migrate - ``` - - The database configuration can be found at `config/test_db.php`. - - -6. Start web server: - - ``` - tests/bin/yii serve - ``` - -7. Now you can run all available tests - - ``` - # run all available tests - vendor/bin/codecept run - - # run acceptance tests - vendor/bin/codecept run acceptance +- [yiithings/yii2-doten](https://github.com/forecho/yiithings/yii2-doten) +- [sizeg/yii2-jwt](https://github.com/forecho/sizeg/yii2-jwt) +- [yiier/yii2-helpers](https://github.com/forecho/yiier/yii2-helpers) - # run only unit and functional tests - vendor/bin/codecept run unit,functional - ``` +Use +------------ -### Code coverage support +At this time, you have a RESTful API server running at `http://127.0.0.1:8000`. It provides the following endpoints: -By default, code coverage is disabled in `codeception.yml` configuration file, you should uncomment needed rows to be able -to collect code coverage. You can run your tests and collect coverage with the following command: +* `GET /health-check`: a health check service provided for health checking purpose (needed when implementing a server cluster) +* `POST /v1/join`: create a user +* `POST /v1/login`: authenticates a user and generates a JWT -``` -#collect coverage for all tests -vendor/bin/codecept run -- --coverage-html --coverage-xml +Try the URL `http://localhost:8000/health-check` in a browser, and you should see something like `{"code":0,"data":"OK","message":"成功"}` displayed. -#collect coverage only for unit tests -vendor/bin/codecept run unit -- --coverage-html --coverage-xml +If you have `cURL` or some API client tools (e.g. [Postman](https://www.getpostman.com/)), you may try the following +more complex scenarios: -#collect coverage for unit and functional tests -vendor/bin/codecept run functional,unit -- --coverage-html --coverage-xml -``` +```shell +# create a user via: POST /v1/join +curl -X POST -H "Content-Type: application/json" -d '{"username":"demo","email":"demo@email.com","password":"pass123"}' http://localhost:8000/v1/join +# should return like: {"code":0,"data":{"username":"demo","email":"demo@email.com","status":1,"created_at":"2020-07-18T16:38:11+08:00","updated_at":"2020-07-18T16:38:11+08:00","id":17},"message":"成功"} -You can see code coverage output under the `tests/_output` directory. +# authenticate the user via: POST /v1/login +curl -X POST -H "Content-Type: application/json" -d '{"username": "demo", "password": "pass123"}' http://localhost:8000/v1/login +# should return like: {"code":0,"data":{"user":{"id":4,"username":"dem211o1","avatar":"","email":"de21mo1@mail.com","status":1,"created_at":"2020-07-17T23:49:39+08:00","updated_at":"2020-07-17T23:49:39+08:00"},"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI6IllpaS1SRVNULUFQSSJ9.eyJpc3MiOiJodHRwOlwvXC9sb2NhbGhvc3QiLCJqdGkiOiJZaWktUkVTVC1BUEkiLCJpYXQiOjE1OTUwNjQ5NzIsImV4cCI6MTU5NTMyNDE3MiwidXNlcm5hbWUiOiJkZW0yMTFvMSIsImlkIjo0fQ.y2NSVQe-TQ08RnXnF-o55h905G9WHo6GYHNaUWlKjDE"},"message":"成功"} +``` \ No newline at end of file diff --git a/composer.json b/composer.json index 1c1088a..1572aa8 100644 --- a/composer.json +++ b/composer.json @@ -1,21 +1,18 @@ { - "name": "yiisoft/yii2-app-basic", - "description": "Yii 2 Basic Project Template", + "name": "forecho/yii2-rest-api", + "description": "Yii 2 REST API Project Template", "keywords": [ "yii2", "framework", + "rest", "basic", "project template" ], - "homepage": "http://www.yiiframework.com/", "type": "project", "license": "BSD-3-Clause", "support": { - "issues": "https://github.com/yiisoft/yii2/issues?state=open", - "forum": "http://www.yiiframework.com/forum/", - "wiki": "http://www.yiiframework.com/wiki/", - "irc": "irc://irc.freenode.net/yii", - "source": "https://github.com/yiisoft/yii2" + "issues": "https://github.com/forecho/yii2-rest-api/issues?state=open", + "source": "https://github.com/forecho/yii2-rest-api" }, "minimum-stability": "stable", "require": { diff --git a/config/web.php b/config/web.php index 4d368c5..99ddbed 100644 --- a/config/web.php +++ b/config/web.php @@ -66,6 +66,7 @@ 'rules' => [ "POST /join" => '/user/join', "POST /login" => '/user/login', + "GET health-check" => 'site/health-check', '///' => '//', ], ], diff --git a/controllers/SiteController.php b/controllers/SiteController.php index cf8e5a6..2a6009c 100644 --- a/controllers/SiteController.php +++ b/controllers/SiteController.php @@ -16,6 +16,14 @@ public function actionIndex() return 'hello yii'; } + /** + * @return string + */ + public function actionHealthCheck() + { + return 'OK'; + } + public function actionError() { $exception = Yii::$app->errorHandler->exception; diff --git a/web/assets/.gitignore b/web/assets/.gitignore deleted file mode 100644 index d6b7ef3..0000000 --- a/web/assets/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -* -!.gitignore diff --git a/web/favicon.ico b/web/favicon.ico deleted file mode 100644 index 580ed73..0000000 Binary files a/web/favicon.ico and /dev/null differ diff --git a/web/index-test.php b/web/index-test.php index 1ec192f..2657737 100644 --- a/web/index-test.php +++ b/web/index-test.php @@ -5,10 +5,11 @@ die('You are not allowed to access this file.'); } -defined('YII_DEBUG') or define('YII_DEBUG', true); -defined('YII_ENV') or define('YII_ENV', 'test'); - require __DIR__ . '/../vendor/autoload.php'; + +defined('YII_DEBUG') or define('YII_DEBUG', env('YII_DEBUG') === 'true'); +defined('YII_ENV') or define('YII_ENV', env('YII_ENV') ?: 'prod'); + require __DIR__ . '/../vendor/yiisoft/yii2/Yii.php'; $config = require __DIR__ . '/../config/test.php'; diff --git a/web/robots.txt b/web/robots.txt deleted file mode 100644 index 6f27bb6..0000000 --- a/web/robots.txt +++ /dev/null @@ -1,2 +0,0 @@ -User-agent: * -Disallow: \ No newline at end of file