Installation¶
HiveApi Application Installation¶
HiveApi can be installed automatically with Composer (recommended way) or manually (via Git or via direct download):
1) Download¶
In the following, both methods are described in short:
1.A) Automatically via Composer¶
- Clone the repo, install dependencies and setup the project:
Option 1: Latest stable release release:
composer create-project hiveapi/framework my-awesome-api
Option 2: Target a specific version:
composer create-project hiveapi/framework my-awesome-api ~major.minor
Option 3: Ongoing development branch dev-master
(unstable):
Heads up!
This may provide (unstable) features from the upcoming releases. You may need to keep syncing your project with the upstream
master
branch and runcomposer update
in order to apply changes!*
composer create-project hiveapi/framework my-awesome-api dev-master
- Edit your
.env
variables to match with your environment (set database credentials, app url, …). - Continue from 2) Database Setup below.
1.B) Manually¶
You can download the code directly from the repository as .zip
file or clone the repository using git
(recommended
approach):
- Clone the repository using
git
:
git clone https://github.com/hiveapi/framework.git
- Install all dependency packages (including containers dependencies):
composer install
- Create a new
.env
file by copying the provided.env.example
file.
cp .env.example .env
Heads up!
heck all variables and edit accordingly!
- Generate a random
APP_KEY
php artisan key:generate
- Delete the existing
.git
folder from the root directory and initialize your own one withgit init
.
2) Database Setup¶
- Migrate the provided database by runing the migration artisan command:
php artisan migrate
- Seed the database with the artisan command:
php artisan hive:seed:deploy
- (optional) By default
HiveApi
seeds a “Super User”, given the defaultadmin
role (the role has no permissions set to it).
To give the admin
role, access to all the seeded permissions in the system, run the following command at any time.
php artisan hive:permissions:toRole admin
If you are using Laradock, you need to run those commands from the workspace
container, you can enter that container
by running docker-compose exec workspace bash
from the Laradock folder.
3) OAuth 2.0 Setup¶
- Create encryption keys to generate secure access tokens and create “personal access” and “password grant” clients, which will be used to generate access tokens for your users or applications:
php artisan passport:install
4) Documentation Setup¶
If you are planning to use ApiDoc JS then proceed with this setup, else skip this and use whatever you prefer:
- Install ApiDocJs using NPM or your favorite dependencies manager:
Install it Globally with -g
or locally in the project without -g
npm install apidoc -g
or install it by just running npm install
on the root of the project, after checking the package.json
file on the
root.
- run
php artisan hive:docs
Behind the scene hive:docs
executes a command like this
apidoc -c app/Containers/Documentation/ApiDocJs/public -f public.php -i app -o public/api/documentation
See the API Docs Generator page for more details.
5) Tests Setup¶
- Open
.env.testing
and set up the environment variables correctly. - Open the
/tests/_data/presets/*
files and adapt theurls
accordingly to fit your domains. - Run the tests
vendor/bin/codecept run
B) Development Environment Setup¶
You can run HiveApi
on your favorite environment. Below you see how you can run it on top of
Vagrant (using Laravel Homestead) or
Docker (using Laradock).
We will see how to use both tools and you can pick one, or you can use other options like Larvel Valet, Laragon or even run it directly on your machine.
Heads up!
The ICANN has now officially approved
.dev
as a generic top level domain (gTLD). Therefore, it is not recommended to use.dev
domains any more in your local development setup! The docs here has been changed to use.develop
instead of.dev
, however, you may change to.localhost
,.test
, or whatever suits your needs.
B.1) Using Docker (with Laradock)¶
Laradock
is a Docker PHP development environment. It facilitate running PHP Apps on Docker.
- Install Laradock.
- Navigate into the
laradock
directory:
cd laradock
This directory contains a docker-compose.yml
file. (From the Laradock
project).
2.1) If you haven’t done so, rename env-example
to .env
.
cp env-example .env
- Run the Docker containers:
docker-compose up -d nginx mysql redis beanstalkd
- Make sure you are setting the
Docker IP
asHost
for theDB
andRedis
in your.env
file. - Add the domain to the
hosts
file:
5.1) Open the hosts file on your local machine /etc/hosts
.
We’ll be using hive.local
as local domain (you can change it if you want).
5.2) Map the domain and its subdomains to 127.0.0.1:
127.0.0.1 hive.local
127.0.0.1 api.hive.local
127.0.0.1 admin.hive.local
If you are using NGINX or Apache, make sure the server_name (in case of NGINX) or ServerName (in case of Apache)
in your the server config file, is set to the following hive.local api.hive.local admin.hive.local
. Also don’t
forget to set your root or DocumentRoot to the public directory inside hive (i.e., hive/public
).
B.2) Using Vagrant (with Laravel Homestead)¶
- Configure Homestead:
1.1) Open the Homestead config file:
homestead edit
1.2) Map the api.hive.local
domain to the project public directory - Example:
sites:
- map: api.hive.local
to: /{full-project-path}/hive/public
1.3) You can also map other domains like hive.local
and admin.hive.local
to other web apps:
- map: hive.local
to: /{full-project-path}/clients/web/user
- map: admin.hive.local
to: /{full-project-path}/clients/web/admin
Note: in the example above the /{full-project-path}/clients/web/xxx
are separate apps, who live in their own
repositories and in different folder than the HiveApi
. If your admins, users or other type of applications are
within HiveApi
, then you must point them all to the HiveApi
project folder /{full-project-path}/hive/public
.
So in that case you would have something like this:
- map: api.hive.local
to: /{full-project-path}/hive/public
- map: hive.local
to: /{full-project-path}/hive/public
- map: admin.hive.local
to: /{full-project-path}/hive/public
- Add the domain to the hosts file:
2.1) Open the hosts file on your local machine /etc/hosts
.
We’ll be using hive.local
as local domain (you can change it if you want).
2.2) Map the domain and its subdomains to the Vagrant IP Address:
192.168.10.10 hive.local
192.168.10.10 api.hive.local
192.168.10.10 admin.hive.local
If you are using NGINX or Apache, make sure the server_name (in case of NGINX) or ServerName (in case of Apache)
in your the server config file, is set to the following hive.local api.hive.local admin.hive.local
. Also don’t
forget to set your root or DocumentRoot to the public directory inside hive (i.e., hive/public
).
2.3) Run the Virtual Machine:
homestead up --provision
If you see No input file specified
on the sub-domains!try running this command homestead halt && homestead up --provision
.
B.3) Using something else¶
If you’re not into virtualization solutions, you can setup your environment directly on your machine. Check the software requirements list.
C) Play¶
Now let’s see it in action
1.a. Open your web browser and visit:
http://hive.local
You should see an HTML page, withHiveApi
in the middle.http://admin.hive.local
You should see an HTML Login page.
1.b. Open your HTTP client and call:
http://api.hive.local/
You should see a JSON response with message:"Welcome to HiveApi."
,http://api.hive.local/v1
You should see a JSON response with message:"Welcome to HiveApi (API V1)."
,
- Make some HTTP calls to the API: