javer / influxdb-odm
Provides a PHP object mapping functionality for InfluxDB
Installs: 21 192
Dependents: 4
Suggesters: 0
Security: 0
Stars: 2
Watchers: 3
Forks: 1
Open Issues: 2
Requires
- php: >=8.1
- doctrine/instantiator: ^1.3.1 || ^2.0
- doctrine/persistence: ^3.0
- influxdb/influxdb-php: ^1.0
Requires (Dev)
- doctrine/annotations: ^1.12 || ^2.0
- phpstan/phpstan: ^1.7
- squizlabs/php_codesniffer: 3.8.*
- swivl/php-coding-standard: ^1.4
Conflicts
- doctrine/annotations: <1.12 || >=3.0
README
The InfluxDB ODM is a library that provides a PHP object mapping functionality for InfluxDB.
Installation
Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.
Open a command console, enter your project directory and execute:
$ composer require javer/influxdb-odm
Usage
The best way to understand the InfluxDB ODM is to see it in action. In this section, you'll walk through each step needed to start persisting measurements to and from InfluxDB.
Create a Measurement Class with Mapping Information
Doctrine allows you to work with InfluxDB in a much more interesting way than just fetching data back and forth as an array. Instead, Doctrine allows you to persist entire objects to InfluxDB and fetch entire objects out of InfluxDB. This works by mapping a PHP class and its properties to entries of a InfluxDB Measurement.
For Doctrine to be able to do this, you have to create "metadata", or
configuration that tells Doctrine exactly how the CpuLoad
class and its
properties should be mapped to InfluxDB. This metadata can be specified
directly inside the CpuLoad
class via annotations:
// src/Measurement/CpuLoad.php namespace App\Measurement; use Javer\InfluxDB\ODM\Mapping\Annotations as InfluxDB; /** * @InfluxDB\Measurement(name="cpu_load") */ class CpuLoad { /** * @InfluxDB\Timestamp(precision="u") */ private ?\DateTime $time = null; /** * @InfluxDB\Tag(name="server_id", type="integer") */ private ?int $serverId = null; /** * @InfluxDB\Tag(name="core_number", type="integer") */ private ?int $coreNumber = null; /** * @InfluxDB\Field(name="load", type="float", countable=true) */ private ?float $load = null; }
or using PHP 8 Attributes:
// src/Measurement/CpuLoad.php namespace App\Measurement; use Javer\InfluxDB\ODM\Mapping\Annotations as InfluxDB; #[InfluxDB\Measurement(name: 'cpu_load')] class CpuLoad { #[InfluxDB\Timestamp(precision: 'u')] private ?\DateTime $time = null; #[InfluxDB\Tag(name: 'server_id', type: 'integer')] private ?int $serverId = null; #[InfluxDB\Tag(name: 'core_number', type: 'integer')] private ?int $coreNumber = null; #[InfluxDB\Field(name: 'load', type: 'float', countable: true)] private ?float $load = null; }
Create Measurement Manager
If you are not using JaverInfluxDBBundle
, you have to create an instance of MeasurementManager:
use Doctrine\Common\Annotations\AnnotationReader; use Javer\InfluxDB\ODM\Connection\ConnectionFactory; use Javer\InfluxDB\ODM\Mapping\Driver\AnnotationDriver; use Javer\InfluxDB\ODM\MeasurementManager; use Javer\InfluxDB\ODM\Repository\RepositoryFactory; $dsn = 'influxdb://localhost:8086/metrics'; $mappingDir = 'src/Measurements'; $mappingDriver = new AnnotationDriver(new AnnotationReader(), $mappingDir); $connectionFactory = new ConnectionFactory(); $repositoryFactory = new RepositoryFactory(); $measurementManager = new MeasurementManager($mappingDriver, $connectionFactory, $repositoryFactory, $dsn);
To be able to use annotations, you will have to install an extra package called doctrine/annotations
.
Using PHP 8 Attributes:
use Javer\InfluxDB\ODM\Connection\ConnectionFactory; use Javer\InfluxDB\ODM\Mapping\Driver\AttributeDriver; use Javer\InfluxDB\ODM\MeasurementManager; use Javer\InfluxDB\ODM\Repository\RepositoryFactory; $dsn = 'influxdb://localhost:8086/metrics'; $mappingDir = 'src/Measurements'; $mappingDriver = new AttributeDriver($mappingDir); $connectionFactory = new ConnectionFactory(); $repositoryFactory = new RepositoryFactory(); $measurementManager = new MeasurementManager($mappingDriver, $connectionFactory, $repositoryFactory, $dsn);
Persisting Objects to InfluxDB
Now that you have a mapped CpuLoad
measurement complete with getter and
setter methods, you're ready to persist data to InfluxDB:
use App\Measurement\CpuLoad; use Javer\InfluxDB\ODM\MeasurementManager; $cpuLoad = new CpuLoad(); $cpuLoad->setTime(new DateTime()); $cpuLoad->setServerId(42); $cpuLoad->setCoreNumber(0); $cpuLoad->setLoad(3.14); /** @var MeasurementManager $measurementManager */ $measurementManager->persist($cpuLoad);
Fetching Objects from InfluxDB
Fetching an object back out of InfluxDB is also possible:
$cpuLoad = $measurementManager->getRepository(CpuLoad::class)->find($time);
When you query for a particular type of object, you always use what's known as its "repository". You can think of a repository as a PHP class whose only job is to help you fetch objects of a certain class. You can access the repository object for a measurement class via:
$repository = $measurementManager->getRepository(CpuLoad::class);
Once you have your repository, you have access to all sorts of helpful methods:
// query by the time $cpuLoad = $repository->find($time); // find *all* CPU metrics $cpuLoads = $repository->findAll(); // find a group of CPU metrics for the particular server $cpuLoads = $repository->findBy(['serverId' => 42]);
You can also take advantage of the useful findBy()
and findOneBy()
methods
to easily fetch objects based on multiple conditions:
// query for one cpuLoad matching by serverId and coreNumber $cpuLoad = $repository->findOneBy(['serverId' => 42, 'coreNumber' => 3]); // query for all cpuLoads matching the serverId, ordered by time desc $cpuLoads = $repository->findBy( ['serverId' => 42], ['time' => 'DESC'] );
Updating an Object
Once you've fetched an object from Doctrine, let's try to update it.
$cpuLoad->setLoad(2.54); $measurementManager->persist($cpuLoad);
Please note that you cannot update value of Timestamp or Tag field, only simple Field can be updated.
Deleting an Object
Deleting an object is very similar, but requires a call to the remove()
method of the measurement manager:
$measurementManager->remove($cpuLoad);
Querying for Objects
As you saw above, the built-in repository class allows you to query for one or many objects based on any number of different parameters. When this is enough, this is the easiest way to query for measurements. You can also create more complex queries.
Using the Query Builder
InfluxDB ODM ships with a query "Builder" object, which allows you to construct a query for exactly which measurements you want to return. If you use an IDE, you can also take advantage of auto-completion as you type the method names. From inside a controller:
$cpuLoads = $measurementManager->createQuery(CpuLoad::class) ->where('serverId', 42) ->orderBy('time', 'ASC') ->limit(10) ->getResult();
Custom Repository Classes
In the previous section, you began constructing and using more complex queries from inside a controller. In order to isolate, test and reuse these queries, it's a good idea to create a custom repository class for your measurement and add methods with your query logic there.
To do this, add the name of the repository class to your mapping definition.
// src/Measurement/CpuLoad.php namespace App\Measurement; use App\Repository\CpuLoadRepository; use Javer\InfluxDB\ODM\Mapping\Annotations as InfluxDB; /** * @InfluxDB\Measurement(name="cpu_load", repositoryClass=CpuLoadRepository::class) */ class CpuLoad { // ... }
You have to create the repository in the namespace indicated above. Make sure it
extends the default MeasurementRepository
. Next, add a new method -
findAllOrderedByTimeDesc()
- to the new repository class. This method will query
for all of the CpuLoad
measurements, ordered by time desc.
// src/Repository/CpuLoadRepository.php namespace App\Repository; use Javer\InfluxDB\ODM\Repository\MeasurementRepository; class CpuLoadRepository extends MeasurementRepository { public function findAllOrderedByTimeDesc(): array { return $this->createQuery() ->orderBy('time', 'DESC') ->getResult(); } }
You can use this new method like the default finder methods of the repository:
$cpuLoads = $measurementManager->getRepository(CpuLoad::class) ->findAllOrderedByTimeDesc();
When using a custom repository class, you still have access to the default
finder methods such as find()
and findAll()
.