katanyoo/yii2-app-api

Yii 2 API Project Template

, _(*1)

Yii 2 RESTful API Project Template

DIRECTORY STRUCTURE

  assets/             contains assets definition
  commands/           contains console commands (controllers)
  config/             contains application configurations
  controllers/        contains Controller classes
  modules/            contains Module for api
    v1/               contains Controller classes and Model classes
      controllers/    contains Module controller classes
      models/         contains Model classes
  mail/               contains view files for e-mails
  runtime/            contains files generated during runtime
  tests/              contains various tests for the api application
  vendor/             contains dependent 3rd-party packages
  views/              contains view files for the Web application
  web/                contains the entry script and Web resources

REQUIREMENTS

The minimum requirement by this project template that your Web server supports PHP 5.4.0., _(*2)

INSTALLATION

Install via Composer

If you do not have Composer, you may install it by following the instructions at getcomposer.org., _(*3)

You can then install this project template using the following command:, _(*4)

php composer.phar create-project --prefer-dist katanyoo/yii2-app-api api

Now you should be able to access the application through the following URL, assuming api is the directory directly under the Web root., _(*5)

http://localhost/api/web/

Install from an Archive File

Extract the archive file downloaded from github.com to a directory named api that is directly under the Web root., _(*6)

Set cookie validation key in config/web.php file to some random secret string:, _(*7)

'request' => [
    // !!! insert a secret key in the following (if it is empty) - this is required by cookie validation
    'cookieValidationKey' => '<secret random string goes here>',
],

You can then access the application through the following URL:, _(*8)

http://localhost/api/web/

CONFIGURATION

API Versioning

Edit the file config/modules.php for each of API versions, _(*9)

Database

Edit the file config/db.php with real data, for example:, _(*10)

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=localhost;dbname=yii2api',
    '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 api application tests., _(*11)

Basic usage (HTTP Client)

Performing HTTP GET request with mime type detection:, _(*12)

// Result is html text
$text = Yii::$app->httpclient->get('http://httpbin.org/html');

// Result is SimpleXMLElement containing parsed XML
$xml = Yii::$app->httpclient->get('http://httpbin.org/xml');

// Result is parsed JSON array
$json = Yii::$app->httpclient->get('http://httpbin.org/get');

You can disable this behavior by specifying $detectMimeType option to whole component or single call, _(*13)

// Result is Guzzle `Response` object
$text = Yii::$app->httpclient->get('http://httpbin.org/xml', [], false);

Make request with custom options:, _(*14)

$text = Yii::$app->httpclient->get('http://httpbin.org/xml', [
    'proxy' => 'tcp://localhost:8125'
]);

Read more about this options in Guzzle 6 documentation, _(*15)

HTTP methods

You can make request with several ways:, _(*16)

1. Call shortcut method (get(), post(), put(), delete(), etc.)
2. Call request() method

All shortcut methods has the same signature except get():, _(*17)

// Synchronous GET request
Yii::$app->httpclient->get(
    $url, // URL
    [], // Options
    true // Detect Mime Type?
);

// Synchronous POST (and others) request
Yii::$app->httpclient->post(
    $url, // URL
    $body, // Body
    [], // Options
    true // Detect Mime Type?
);

// Asynchronous GET request
Yii::$app->httpclient->getAsync(
    $url, // URL
    [] // Options
);

// Asynchronous POST (and others) request
Yii::$app->httpclient->postAsync(
    $url, // URL
    $body, // Body
    [] // Options
);

NOTE: you still can make a GET request with body via request() function, _(*18)

Asynchronous calls

To make an asynchronous request simly add Async to end of request method:, _(*19)

// PromiseInterface
$promise = Yii::$app->httpclient->postAsync('http://httpbin.org/post');

NOTE: mime type detection is not supported for asynchronous calls, _(*20)

Read more about asynchronous requests in Guzzle 6 documentation, _(*21)

Request body

Types you can pass as a body of request:, _(*22)

1. __Arrayable object__ (ActiveRecord, Model etc.) - will be encoded into JSON object
2. Array - will be sent as form request (x-form-urlencoded)

Any other data passed as body will be sent into Guzzle without any transformations., _(*23)

Read more about request body in Guzzle documentation, _(*24)

API Document Generating

./yii doc/gen

For Windows user, _(*25)

yii doc/win-gen