This repo contains the PHP backend code for the Smart Flanders project.
To install the project, run composer install
.
Make sure the out
and resources
directories are writable for the data gathering cron job (see further):
mkdir out resources
chmod 777 out resources
Note that some parameters in the project are stored in a .env
file (https://github.com/vlucas/phpdotenv).
The .env
file is not included in the repository because some of these parameters are confidential. However,
we have provided an example .env
file. To use it, run cp .env.example .env
.
This will make the Gent and Kortrijk datasets work (see further for hosting details).
The file cron.php
is set up to gather data from the available datasets. To activate the data gathering, add
the following line to your crontab (crontab -e
):
* * * * * /bin/php [INSTALLATION_FOLDER]/cron.php 1>> /dev/null 2>&1
Make sure you've set up data gathering before running any servers. Without files, nothing can be hosted. A test server can be hosted as follows:
php -S 127.0.0.1:80 -t src/
The server reads the subdomain to determine the dataset that needs to be returned (this subdomain must be the dataset
name in lower case, see 'Adding new datasets'). In order to test locally, a url needs to be added to /etc/hosts
for
each dataset. For the example .env file, this is as follows:
127.0.0.1 localhost gent.smartflanders.com kortrijk.smartflanders.com smartflanders.com
/entry
: returns a JSON file with all the valid URLs of dataset hosted on this server.<city>.<domain>/parking
: returns the latest measurements of this city (dataset) in a Turtle file.<city>.<domain>/parking?time=YYYY-MM-DDTHH:mm:ss
: returns the most recent measurement file before the given timestamp.
To add a new dataset, the interface IGraphProcessor
in Helpers
must be implemented.
Some examples are available in src/Datasets
(note that some URLs and credentials use Dotenv to
hide confidential information). The interface defines the following methods:
getDynamicGraph()
: Return a graph containing the data that should be continuously measured (e.g. available parking spaces in a parking dataset). This data will be saved to disk for each query. It therefore shouldn't contain data that will always remain the same.getStaticGraph()
: Return a graph containing static data. This is data that is not expected to change (e.g. a geographic location of a parking site). This data is saved to disk only once.getName()
: Return the name of the dataset. This name will be used to identify the dataset in the subdomain.getBaseUrl()
: Return the URL on which the dataset is to be published. This URL will be used in the stored files, so it will be visible to the public.getRealTimeMaxAge()
: Return the amount of seconds the dynamic data can be cached. This will be put in the cache headers of the dataset.
In order for the cron job to gather data for the new dataset, it must be defined in the .env file. The following variables must be created/updated to add the new dataset:
DATASETS
: contains a comma-separated list of dataset names. The name of the dataset must be added here (it is recommended to use the same name here as ingetName()
)[DATASET_NAME]_PATH
: Contains the fully classified class name for the given dataset.[DATASET_NAME]
here must be the same name as added inDATASETS
.
There are two ways in which a new dataset can be published: either it will be published on its own (no router needed), or it will be added to an existing group of datasets (using the router).
To publish one dataset, the routing component in index.php
is not necessary. An example index.php
for a single dataset can be found in index-singular.php
. Here, you simply fill in the Graph Processor in the
$graph_processor
variable and point your server to the src/
directory.
To add a new dataset to an existing group of datasets, the router needs to be used.
The router identifies datasets using subdomains (the first part of the domain must be a dataset name).
This means that getBaseUrl()
in the Graph Processor should return a URL starting with the dataset name.
Note that the relevant URLs must be added to /etc/hosts
for local testing (see above: Local Testing).