ravendb / ravendb-php-client
RavenDB PHP client
Requires
- php: >=8.1
- ext-ds: *
- ext-fileinfo: *
- ext-json: *
- ext-zip: *
- doctrine/annotations: ^1.13
- doctrine/inflector: ^2.0
- ramsey/uuid: ^4.2
- symfony/http-client: ^6.1
- symfony/mime: ^6.1
- symfony/property-access: ^6.1
- symfony/serializer: ^6.1
Requires (Dev)
- phpstan/phpstan: ^0.12.98
- phpunit/phpunit: ~9.6
- squizlabs/php_codesniffer: ^3.0
This package is not auto-updated.
Last update: 2024-11-06 23:37:24 UTC
README
Installation
You can install library to your project via Composer
$ composer require ravendb/ravendb-php-client
Releases
-
All client versions 5.2.x are fully compatible with and support RavenDB server releases 5.4 and 6.0.
-
Click here to view all Releases and Changelog.
Documentation
This readme provides short examples for the following:
Getting started,
Crud example,
Query documents,
Attachments,
Time series,
Revisions,
Suggestions,
Patching,
Using classes,
PHP usage,
Working with secure server,
Running tests
For more information go to the online RavenDB Documentation.
For more information on how to use RavenDB with Laravel check out the Raven Laravel Demo Application
Getting started
- Require the
DocumentStore
class from the ravendb package
use RavenDB\Documents\DocumentStore;
- Initialize the document store (you should have a single DocumentStore instance per application)
$store = new DocumentStore('http://live-test.ravendb.net', 'databaseName'); $store->initialize();
- Open a session
$session = $store->openSession();
- Call
saveChanges()
when you're done
$user = $session->load('users/1-A'); // Load document $user->setPassword(PBKDF2('new password')); // Update data $session->saveChanges(); // Save changes // Data is now persisted // You can proceed e.g. finish web request
CRUD example
Store documents
$product = new Product(); $product->setTitle("iPhone X"); $product->setPrice(999.99); $product->setCurrency("USD"); $product->setStorage(64); $product->setManufacturer("Apple"); $product->setInStock(true); $session->store($product, 'products/1-A'); echo $product->id; // products/1-A $session->saveChanges();
Related tests:
Load documents
$product = $session->load(Product::class, 'products/1-A'); echo $product->getTitle(); // iPhone X echo $product->getId(); // products/1-A
Load documents with include
// users/1 // { // "name": "John", // "kids": ["users/2", "users/3"] // } $session = $store->openSession(); try { $user1 = $session ->include("kids") ->load("users/1"); // Document users/1 and all docs referenced in "kids" // will be fetched from the server in a single request. $user2 = $session->load("users/2"); // this won't call server again $this->assertNotNull($user1); $this->assertNotNull($user2); $this->assertEqual(1, $session->advanced()->getNumberOfRequests()); } finally { $session->close(); }
Related tests:
Update documents
$product = $session->load(Product::class, 'products/1-A'); $product->setInStock(false); $product->setLastUpdate(new Date()); $session->saveChanges(); // ... $product = $session->load(Product::class, 'products/1-A'); echo $product->getInStock(); // false echo $product->getLastUpdate(); // the current date
Delete documents
- Using entity
$product = $session->load('products/1-A'); $session->delete($product); $session->saveChanges(); $product = $session->load('products/1-A'); $this->assertNull($product); // null
- Using document ID
$session->delete('products/1-A');
Related tests:
delete doc by entity
delete doc by ID
onBeforeDelete is called before delete by ID
cannot delete untracked entity
loading deleted doc returns null
Query documents
- Use
query()
session method:
Query by collection:
$query = $session->query(Product::class, Query::collection('products'));
Query by index name:
$query = $session->query(Product::class, Query::indexName('productsByCategory'));
Query by index:
$query = $session->query(Product::class, Products_ByCategory::class);
Query by entity type:
$query = $session->query(Product::class);
- Build up the query - apply search conditions, set ordering, etc.
Query supports chaining calls:
$query ->waitForNonStaleResults() ->usingDefaultOperator('AND') ->whereEquals('manufacturer', 'Apple') ->whereEquals('in_stock', true) ->whereBetween('last_update', new DateTime('- 1 week'), new DateTime()) ->orderBy('price');
- Execute the query to get results:
$results = $query->toList(); // get all results // ... $firstResult = $query->first(); // gets first result // ... $single = $query->single(); // gets single result
Query methods overview
selectFields() - projections using a single field
// RQL // from users select name // Query $userNames = $session->query(User::class) ->selectFields("name") ->toList(); // Sample results // John, Stefanie, Thomas
Related tests:
selectFields() - projections using multiple fields
// RQL // from users select name, age // Query $session->query(User::class) ->selectFields([ "name", "age" ]) ->toList(); // Sample results // [ [ name: 'John', age: 30 ], // [ name: 'Stefanie', age: 25 ], // [ name: 'Thomas', age: 25 ] ]
Related tests:
distinct()
// RQL // from users select distinct age // Query $session->query(User::class) ->selectFields("age") ->distinct() ->toList(); // Sample results // [ 30, 25 ]
Related tests:
whereEquals() / whereNotEquals()
// RQL // from users where age = 30 // Query $session->query(User::class) ->whereEquals("age", 30) ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // kids: [...], // registeredAt: 2017-11-10T23:00:00.000Z } ]
Related tests:
whereIn()
// RQL // from users where name in ("John", "Thomas") // Query $session->query(User::class) ->whereIn("name", ["John", "Thomas"]) ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: [...], // id: 'users/1-A' }, // User { // name: 'Thomas', // age: 25, // registeredAt: 2016-04-24T22:00:00.000Z, // id: 'users/3-A' } ]
Related tests:
whereStartsWith() / whereEndsWith()
// RQL // from users where startsWith(name, 'J') // Query $session->query(User::class) ->whereStartsWith("name", "J") ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // kids: [...], // registeredAt: 2017-11-10T23:00:00.000Z } ]
Related tests:
whereBetween()
// RQL // from users where registeredAt between '2016-01-01' and '2017-01-01' // Query $session->query({ collection: "users" }) ->whereBetween("registeredAt", DateTime::createFromFormat('Y-m-d', '2016-01-01'), DateTime::createFromFormat('Y-m-d', '2017-01-01')) ->toList(); // Sample results // [ User { // name: 'Thomas', // age: 25, // registeredAt: 2016-04-24T22:00:00.000Z, // id: 'users/3-A' } ]
Related tests:
whereGreaterThan() / whereGreaterThanOrEqual() / whereLessThan() / whereLessThanOrEqual()
// RQL // from users where age > 29 // Query $session->query(User::class) ->whereGreaterThan("age", 29) ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: [...], // id: 'users/1-A' } ]
Related tests:
query with where less than
query with where less than or equal
query with where greater than
query with where greater than or equal
whereExists()
Checks if the field exists.
// RQL // from users where exists("age") // Query $session->query(User::class) ->whereExists("kids") ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: [...], // id: 'users/1-A' } ]
Related tests:
containsAny() / containsAll()
// RQL // from users where kids in ('Mara') // Query $session->query(User::class) ->containsAll("kids", ["Mara", "Dmitri"]) ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: ["Dmitri", "Mara"] // id: 'users/1-A' } ]
Related tests:
search()
Perform full-text search.
// RQL // from users where search(kids, 'Mara') // Query $session->query(User::class) ->search("kids", "Mara Dmitri") ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: ["Dmitri", "Mara"] // id: 'users/1-A' } ]
Related tests:
query search with or
query_CreateClausesForQueryDynamicallyWithOnBeforeQueryEvent
openSubclause() / closeSubclause()
// RQL // from users where exists(kids) or (age = 25 and name != Thomas) // Query $session->query(User::class) ->whereExists("kids") ->orElse() ->openSubclause() ->whereEquals("age", 25) ->whereNotEquals("name", "Thomas") ->closeSubclause() ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: ["Dmitri", "Mara"] // id: 'users/1-A' }, // User { // name: 'Stefanie', // age: 25, // registeredAt: 2015-07-29T22:00:00.000Z, // id: 'users/2-A' } ]
Related tests:
not()
// RQL // from users where age != 25 // Query $session->query(User::class) ->not() ->whereEquals("age", 25) ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: ["Dmitri", "Mara"] // id: 'users/1-A' } ]
Related tests:
orElse() / andAlso()
// RQL // from users where exists(kids) or age < 30 // Query $session->query(User::class) ->whereExists("kids") ->orElse() ->whereLessThan("age", 30) ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: [ 'Dmitri', 'Mara' ], // id: 'users/1-A' }, // User { // name: 'Thomas', // age: 25, // registeredAt: 2016-04-24T22:00:00.000Z, // id: 'users/3-A' }, // User { // name: 'Stefanie', // age: 25, // registeredAt: 2015-07-29T22:00:00.000Z, // id: 'users/2-A' } ]
Related tests:
usingDefaultOperator()
If neither andAlso()
nor orElse()
is called then the default operator between the query filtering conditions will be AND
.
You can override that with usingDefaultOperator
which must be called before any other where conditions.
// RQL // from users where exists(kids) or age < 29 // Query $session->query(User::class) ->usingDefaultOperator("OR") // override the default 'AND' operator ->whereExists("kids") ->whereLessThan("age", 29) ->toList(); // Sample results // [ User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: [ 'Dmitri', 'Mara' ], // id: 'users/1-A' }, // User { // name: 'Thomas', // age: 25, // registeredAt: 2016-04-24T22:00:00.000Z, // id: 'users/3-A' }, // User { // name: 'Stefanie', // age: 25, // registeredAt: 2015-07-29T22:00:00.000Z, // id: 'users/2-A' } ]
orderBy() / orderByDesc() / orderByScore() / randomOrdering()
// RQL // from users order by age // Query $session->query(User::class) ->orderBy("age") ->toList(); // Sample results // [ User { // name: 'Stefanie', // age: 25, // registeredAt: 2015-07-29T22:00:00.000Z, // id: 'users/2-A' }, // User { // name: 'Thomas', // age: 25, // registeredAt: 2016-04-24T22:00:00.000Z, // id: 'users/3-A' }, // User { // name: 'John', // age: 30, // registeredAt: 2017-11-10T23:00:00.000Z, // kids: [ 'Dmitri', 'Mara' ], // id: 'users/1-A' } ]
Related tests:
query random order
order by AlphaNumeric
query with boost - order by score
take()
Limit the number of query results.
// RQL // from users order by age // Query $session->query(User::class) ->orderBy("age") ->take(2) // only the first 2 entries will be returned ->toList(); // Sample results // [ User { // name: 'Stefanie', // age: 25, // registeredAt: 2015-07-29T22:00:00.000Z, // id: 'users/2-A' }, // User { // name: 'Thomas', // age: 25, // registeredAt: 2016-04-24T22:00:00.000Z, // id: 'users/3-A' } ]
Related tests:
skip()
Skip a specified number of results from the start.
// RQL // from users order by age // Query $session->query(User::class) ->orderBy("age") ->take(1) // return only 1 result ->skip(1) // skip the first result, return the second result ->toList(); // Sample results // [ User { // name: 'Thomas', // age: 25, // registeredAt: 2016-04-24T22:00:00.000Z, // id: 'users/3-A' } ]
Related tests:
Getting query statistics
Use the statistics()
method to obtain query statistics.
// Query $stats = new QueryStatistics(); $results = $session->query(User::class) ->whereGreaterThan("age", 29) ->statistics($stats) ->toList(); // Sample results // QueryStatistics { // isStale: false, // durationInMs: 744, // totalResults: 1, // skippedResults: 0, // timestamp: 2018-09-24T05:34:15.260Z, // indexName: 'Auto/users/Byage', // indexTimestamp: 2018-09-24T05:34:15.260Z, // lastQueryTime: 2018-09-24T05:34:15.260Z, // resultEtag: 8426908718162809000 }
all() / first() / single() / count()
all()
- returns all results
first()
- first result only
single()
- first result, throws error if there's more entries
count()
- returns the number of entries in the results (not affected by take()
)
Related tests:
Attachments
Store attachments
$doc = new User(); $doc->setName('John'); // Store a document, the entity will be tracked. $session->store($doc); // Get read stream or buffer to store $fileStream = file_get_contents("../photo.png"); // Store attachment using entity $session->advanced()->attachments()->store($doc, "photo.png", $fileStream, "image/png"); // OR store attachment using document ID $session->advanced()->attachments()->store($doc->getId(), "photo.png", $fileStream, "image/png"); // Persist all changes $session->saveChanges();
Related tests:
Get attachments
// Get an attachment $attachment = $session->advanced()->attachments()->get($documentId, "photo.png") // Attachment.details contains information about the attachment: // { // name: 'photo.png', // documentId: 'users/1-A', // contentType: 'image/png', // hash: 'MvUEcrFHSVDts5ZQv2bQ3r9RwtynqnyJzIbNYzu1ZXk=', // changeVector: '"A:3-K5TR36dafUC98AItzIa6ow"', // size: 4579 // } // Attachment.data is a Readable. $fileBytes = $attachment->getData(); file_put_contents('../photo.png', $fileBytes);
Related tests:
Check if attachment exists
$session->advanced()->attachments()->exists($doc->getId(), "photo.png"); // true $session->advanced()->attachments()->exists($doc->getId(), "not_there.avi"); // false
Related tests:
Get attachment names
// Use a loaded entity to determine attachments' names $session->advanced()->attachments()->getNames($doc); // Sample results: // [ { name: 'photo.png', // hash: 'MvUEcrFHSVDts5ZQv2bQ3r9RwtynqnyJzIbNYzu1ZXk=', // contentType: 'image/png', // size: 4579 } ]
Related tests:
TimeSeries
Store time series
$session = $store->openSession(); // Create a document with time series $session->store(new User(), "users/1"); $tsf = $session->timeSeriesFor("users/1", "heartbeat"); // Append a new time series entry $tsf->append(new DateTime(), 120); $session->saveChanges();
Related tests:
canCreateSimpleTimeSeries
usingDifferentTags
canStoreAndReadMultipleTimestamps
canStoreLargeNumberOfValues
shouldDeleteTimeSeriesUponDocumentDeletion
Get time series for document
$session = $store->openSession(); // Get time series for document by time series name $tsf = $session->timeSeriesFor("users/1", "heartbeat"); // Get all time series entries $heartbeats = $tsf->get();
Related tests:
canCreateSimpleTimeSeries
canStoreLargeNumberOfValues
canRequestNonExistingTimeSeriesRange
canGetTimeSeriesNames2
canSkipAndTakeTimeSeries
Revisions
NOTE: Please make sure revisions are enabled before trying the below.
$user = new User(); $user->setName("Marcin"); $user->setAge(30); $user->setPet("Cat"); $session = $store->openSession(); // Store a document $session->store($user, "users/1"); $session->saveChanges(); // Modify the document to create a new revision $user->setName("Roman"); $user->setAge(40); $session->saveChanges(); // Get revisions $revisions = $session->advanced()->revisions()->getFor("users/1"); // Sample results: // [ { name: 'Roman', // age: 40, // pet: 'Cat', // '@metadata': [Object], // id: 'users/1' }, // { name: 'Marcin', // age: 30, // pet: 'Cat', // '@metadata': [Object], // id: 'users/1' } // ]
Suggestions
Suggest options for similar/misspelled terms
// Some documents in users collection with misspelled name term // [ User { // name: 'Johne', // age: 30, // ... // id: 'users/1-A' }, // User { // name: 'Johm', // age: 31, // ... // id: 'users/2-A' }, // User { // name: 'Jon', // age: 32, // ... // id: 'users/3-A' }, // ] // Static index definition class UsersIndex extends AbstractJavaScriptIndexCreationTask { public function __construct() { parent::__construct(); $this->map = "from user in docs.users select new { user.name }"; // Enable the suggestion feature on index-field 'name' $this->suggestion("name"); } } // ... $session = $store->openSession(); // Query for similar terms to 'John' // Note: the term 'John' itself will Not be part of the results $suggestedNameTerms = $session->query(User::class, UsersIndex::class) ->suggestUsing(function($x) { return $x->byField("name", "John"); }) ->execute(); // Sample results: // { name: { name: 'name', suggestions: [ 'johne', 'johm', 'jon' ] } }
Advanced patching
// Increment 'age' field by 1 $session->advanced()->increment("users/1", "age", 1); // Set 'underAge' field to false $session->advanced->patch("users/1", "underAge", false); $session->saveChanges();
Related tests:
can patch
can patch complex
can add to array
can increment
patchWillUpdateTrackedDocumentAfterSaveChanges
can patch single document
Using classes for entities
- Define your model as class. Attributes should be just public properties:
class Product { public ?string $id = null, public string $title = '', public int $price = 0, public string $currency = 'USD', public int $storage = 0, public string $manufacturer = '', public bool $in_stock = false, public ?DateTime $last_update = null public function __construct( $id = null, $title = '', $price = 0, $currency = 'USD', $storage = 0, $manufacturer = '', $in_stock = false, $last_update = null ) { $this->id = $id; $this->title = $title; $this->price = $price; $this->currency = $currency; $this->storage = $storage; $this->manufacturer = $manufacturer; $this->in_stock = $in_stock; $this->last_update = $last_update ?? new DateTime(); } }
- To store a document pass its instance to
store()
.
The collection name will automatically be detected from the entity's class name.
use models\Product; $product = new Product( null, 'iPhone X', 999.99, 'USD', 64, 'Apple', true, new Date('2017-10-01T00:00:00')); $product = $session->store($product); var_dump($product instanceof Product); // true var_dump(str_starts_with($product->id, 'products/')); // true $session->saveChanges();
- Loading a document
$product = $session->load('products/1-A'); var_dump($product instanceof Product); // true var_dump($product->id); // products/1-A
- Querying for documents
$products = $session->query(Product::class)->toList(); foreach($products as $product) { var_dump($product instanceof Product); // true var_dump(str_starts_with($product->id, 'products/')); // true });
Usage with PHP
PHP typings are embedded into the package. Make sure to close session when you finish your work with it.
// file models/product.php class Product { public ?string $id = null, public string $title = '', public int $price = 0, public string $currency = 'USD', public int $storage = 0, public string $manufacturer = '', public bool $in_stock = false, public ?DateTime $last_update = null public function __construct( $id = null, $title = '', $price = 0, $currency = 'USD', $storage = 0, $manufacturer = '', $in_stock = false, $last_update = null ) { $this->id = $id; $this->title = $title; $this->price = $price; $this->currency = $currency; $this->storage = $storage; $this->manufacturer = $manufacturer; $this->in_stock = $in_stock; $this->last_update = $last_update ?? new DateTime(); } } // file app.php use models\Product; use RavenDB\Documents\DocumentStore; use RavenDB\Documents\Session\DocumentSession; $store = new DocumentStore('url', 'database name'); try { $store->initialize(); $productId = null; /** @var DocumentSession $session */ $session = $store->openSession(); try { $product = new Product( null, 'iPhone X', 999.99, 'USD', 64, 'Apple', true, new Date('2017-10-01T00:00:00')); $session->store($product); $session->saveChanges(); var_dump($product instanceof Product); // true var_dump(str_starts_with($product->id, 'products/')); // true $productId = $product->id; } finally { $session->close(); } $session = $store->openSession(); try { /** @var Product $product */ $product = $session->load(Product::class, $productId); var_dump($product instanceof Product); // true var_dump($product->id); // products/1-A /** @var array<Product> $products */ $products = $session->query(Query::collection('Products')) ->waitForNonStaleResults() ->whereEquals('manufacturer', 'Apple') ->whereEquals('in_stock', true) ->whereBetween('last_update', new DateTime('- 1 week'), new DateTime()) ->whereGreaterThanOrEqual('storage', 64) ->toList(); foreach ($products as $product) { var_dump($product instanceof Product); // true var_dump(str_starts_with($product->id, 'products/')); // true } } finally { $session->close(); } } finally { $store->close(); }
Working with a secure server
Your certificate and server certificate should be saved in PEM format to your machine.
- Create AuthOptions:
$authOptions = AuthOptions::pem( '../clientCertPath.pem', 'clientCertPass', '../serverCaCertPath.pem' );
- Pass auth options to
DocumentStore
object:
$store = new DocumentStore('url', 'databaseName'); $store->setAuthOptions($authOptions); // use auth options to connect on database $store->initialize();
Running tests
Clone the repository:
git clone https://github.com/ravendb/ravendb-php-client
Install dependencies:
composer install
Run RavenDB server
https://a.phptest.development.run
Set environment variables.
# Set the following environment variables: # # - Certificate hostname # RAVENDB_PHP_TEST_HTTPS_SERVER_URL=https://a.phptest.development.run # # RAVENDB_PHP_TEST_CA_PATH= # # - Certificate path for tests requiring a secure server: # RAVENDB_PHP_TEST_CERTIFICATE_PATH= # # - Certificate for client # RAVENDB_TEST_CLIENT_CERT_PATH= # RAVENDB_TEST_CLIENT_CERT_PASSPHRASE= # # - For some tests, Developers licence is required in order to run them all # RAVEN_LICENSE=
Run PHPUnit
./vendor/bin/phpunit
Bug Tracker
http://issues.hibernatingrhinos.com/issues/RDBC
License
The MIT License (MIT). Please see License File for more information.