neo4j php client
ved error handling
Para algumas redigas mais detalhadas, você pode consultar estes posts do blog:
Ou assista a qualquer um desses vídeos.
composer require laudis/neo4j-php-clientEncontre mais detalhes aqui
use Laudis Neo4j Authentication Authenticate ;
use Laudis Neo4j ClientBuilder ;
$ client = ClientBuilder:: create ()
-> withDriver ( ' bolt ' , ' bolt+s://user:password@localhost ' ) // creates a bolt driver
-> withDriver ( ' https ' , ' https://test.com ' , Authenticate:: basic ( ' user ' , ' password ' )) // creates an http driver
-> withDriver ( ' neo4j ' , ' neo4j://neo4j.test.com?database=my-database ' , Authenticate:: oidc ( ' token ' )) // creates an auto routed driver with an OpenID Connect token
-> withDefaultDriver ( ' bolt ' )
-> build ();Agora você criou um cliente com drivers Bolt, Https e Neo4J . O driver padrão que o cliente usará é o parafuso .
Leia mais sobre os URLs e como usá -los para configurar os motoristas aqui.
use Laudis Neo4j Contracts TransactionInterface ;
$ result = $ client -> writeTransaction ( static function ( TransactionInterface $ tsx ) {
$ result = $ tsx -> run ( ' MERGE (x {y: "z"}:X) return x ' );
return $ result -> first ()-> get ( ' x ' )[ ' y ' ];
});
echo $ result ; // echos 'z' Você pode controlar o motorista usando três abordagens diferentes:
As consultas cometidas automáticas são as mais diretas e intuitivas, mas têm muitas desvantagens ao executar a lógica de negócios complexa ou dentro de um ambiente de alta disponibilidade.
$ client -> run (
' MERGE (user {email: $email}) ' , //The query is a required parameter
[ ' email ' => ' [email protected] ' ], //Requests can be optionally added
' backup ' //The default connection can be overridden
); use Laudis Neo4j Databags Statement ;
$ statement = new Statement ( ' MERGE (user {email: $email}) ' , [ ' email ' => ' [email protected] ' ]);
$ client -> runStatement ( $ statement , ' default ' ); O método runStatements executará todas as declarações de uma só vez. Este método é uma ferramenta essencial para reduzir o número de chamadas de banco de dados, especialmente ao usar o protocolo HTTP.
use Laudis Neo4j Databags Statement ;
$ results = $ client -> runStatements ([
Statement:: create ( ' MATCH (x) RETURN x LIMIT 100 ' ),
Statement:: create ( ' MERGE (x:Person {email: $email}) ' , [ ' email ' => ' [email protected] ' ])
]);As funções de transação são o padrão de fato ao usar o driver. É o mais portátil, pois é resistente a muitas armadilhas ao se desenvolver pela primeira vez com soluções de alta disponibilidade, como Neo4J Aura ou um cluster.
O motorista gerencia funções de transação:
ATENÇÃO: Devido à funcionalidade automática da tentativa, a função deve produzir o mesmo resultado em recalls subsequentes ou em termos mais técnicos: deve ser idempotente . Lembre -se sempre disso ao projetar a lógica de execução dentro da função.
Alguns exemplos:
use Laudis Neo4j Contracts TransactionInterface ;
// Do a simple merge and return the result
$ result = $ client -> writeTransaction ( static function ( TransactionInterface $ tsx ) {
$ result = $ tsx -> run ( ' MERGE (x {y: "z"}:X) return x ' );
return $ result -> first ()-> get ( ' x ' )[ ' y ' ];
});
// Will result in an error
$ client -> readTransaction ( static function ( TransactionInterface $ tsx ) {
$ tsx -> run ( ' MERGE (x {y: "z"}:X) return x ' );
});
// This is a poorly designed transaction function
$ client -> writeTransaction ( static function ( TransactionInterface $ tsx ) use ( $ externalCounter ) {
$ externalCounter -> incrementNodesCreated ();
$ tsx -> run ( ' MERGE (x {y: $id}:X) return x ' , [ ' id ' => Uuid:: v4 ()]);
});
// This achieves the same effect but is safe in case it should be retried. The function is now idempotent.
$ id = Uuid:: v4 ();
$ client -> writeTransaction ( static function ( TransactionInterface $ tsx ) use ( $ id ) {
$ tsx -> run ( ' MERGE (x {y: $id}:X) return x ' , [ ' id ' => $ id ]);
});
$ externalCounter -> incrementNodesCreated ();Se você precisar de acesso de nível inferior aos recursos dos drivers, deseja transações não gerenciadas. Eles permitem compromissos e reversões completamente controláveis.
O método beginTransaction iniciará uma transação com o driver relevante.
use Laudis Neo4j Databags Statement ;
$ tsx = $ client -> beginTransaction (
// This is an optional set of statements to execute while opening the transaction
[Statement:: create ( ' MERGE (x:Person({email: $email}) ' , [ ' email ' => ' [email protected] ' ])],
' backup ' // This is the optional connection alias
);Observe que o
beginTransactionretorna apenas o objeto de transação, não os resultados das instruções fornecidas.
A transação pode executar instruções como o objeto cliente, desde que ainda esteja aberto.
$ result = $ tsx -> run ( ' MATCH (x) RETURN x LIMIT 100 ' );
$ result = $ tsx -> runStatement (Statement:: create ( ' MATCH (x) RETURN x LIMIT 100 ' ));
$ results = $ tsx -> runStatements ([Statement:: create ( ' MATCH (x) RETURN x LIMIT 100 ' )]);Rollback uma transação:
$ tsx -> rollback ();Cometer uma transação:
$ tsx -> commit ([Statement:: create ( ' MATCH (x) RETURN x LIMIT 100 ' )]);Os resultados são retornados em um formato padrão de linhas e colunas:
// Results are a CypherList
$ results = $ client -> run ( ' MATCH (node:Node) RETURN node, node.id AS id ' );
// A row is a CypherMap
foreach ( $ results as $ result ) {
// Returns a Node
$ node = $ result -> get ( ' node ' );
echo $ node -> getProperty ( ' id ' );
echo $ result -> get ( ' id ' );
}Os valores e tipos de cifra são mapeados para esses tipos e classes de PHP:
| Cifra | Php |
|---|---|
| nulo | * null |
| corda | * string |
| Inteiro | * int |
| flutuador | * float |
| booleano | * bool |
| Mapa | * LaudisNeo4jTypesCypherMap |
| Lista | * LaudisNeo4jTypesCypherList |
| Apontar | * LaudisNeo4jContractsPointInterface ** |
| Data | * LaudisNeo4jTypesDate |
| Tempo | * LaudisNeo4jTypesTime |
| LocalTime | * LaudisNeo4jTypesLocalTime |
| DateTime | * LaudisNeo4jTypesDateTime |
| DATETIMEZONEID | * LaudisNeo4jTypesDateTimeZoneId |
| LocalDateTime | * LaudisNeo4jTypesLocalDateTime |
| Duração | * LaudisNeo4jTypesDuration |
| Nó | LaudisNeo4jTypesNode |
| Relação | LaudisNeo4jTypesRelationship |
| Caminho | LaudisNeo4jTypesPath |
(*) Esses itens também podem ser usados como parâmetros no protocolo do parafuso e serão automaticamente convertidos pelo driver, para que possam ser usados no Cypher.
Além desses exemplos, DateTimeInterface será mapeado para DateTimeZoneId em Cypher. Uma array vazia ou do tipo listagem será convertida em uma List de cifras, e uma associative array será convertida em um map .
(**) Um ponto pode ser um dos quatro tipos que implementam o PointInterface: LaudisNeo4jTypesCartesianPoint LaudisNeo4jTypesCartesian3DPoint laudis neo4j types wggs84point LaudisNeo4jTypesWGS843DPoint LaudisNeo4jTypesWGS84Point
Cypher tem listas e mapas. Essa noção pode ser problemática, pois as matrizes PHP padrão encapsulam as duas. Quando você fornece uma matriz vazia como parâmetro, será impossível determinar uma lista ou mapa vazio.
A classe ParameterHelper é o companheiro ideal para isso:
use Laudis Neo4j ParameterHelper ;
$ client -> run ( ' MATCH (x) WHERE x.slug in $listOrMap RETURN x ' , [ ' listOrMap ' => ParameterHelper:: asList ([])]); // will return an empty CypherList
$ client -> run ( ' MATCH (x) WHERE x.slug in $listOrMap RETURN x ' , [ ' listOrMap ' => ParameterHelper:: asMap ([])]); // will error
$ client -> run ( ' MATCH (x) WHERE x.slug in $listOrMap RETURN x ' , [ ' listOrMap ' => []]); // will return an empty CypherList| Versão do driver | Versão php | Versão neo4j |
|---|---|---|
| ^2.8 | 7.4, ^8.0 | ^3.5, ^4.0 |
| ^3.0 | ^8.0 | ^4.0, ^5.0 |
| Recurso | Suportado? |
|---|---|
| Autenticação | Sim |
| Transações | Sim |
| Protocolo HTTP | Sim |
| Protocolo de parafuso | Sim |
| Conjunto | Sim |
| Aura | Sim |
| Protocolo Jolt | Sim |
| Marcadores | Sim |
(*) Necessário para implementar o protocolo de parafuso
(**) necessário para implementar o protocolo HTTP
(***) pode ser instalado para o desempenho ideal do protocolo do parafuso
Se você planeja usar os drivers HTTP, verifique se possui implementações PSR-7, PSR-17 e PSR-18 incluídas no projeto. Se você não tiver, pode instalá -los via compositor:
composer require nyholm/psr7 nyholm/psr7-server kriswallsmith/buzzPara tornar os resultados do protocolo do parafuso e do uniforme HTTP, o driver fornece formatados de resultados (também conhecidos como hidratantes). O cliente é configurável com esses formatados. Você pode até implementar o seu próprio.
O formatador padrão é o LaudisNeo4jFormattersOGMFormatter , que é explicado extensivamente na seção de formato de resultado.
O motorista fornece três formatados por padrão, todos encontrados no espaço para nome do formatador:
LaudisNeo4jFormatterBasicFormatter que apaga todos os tipos de cifra e simplesmente retorna todos os valores no mapa resultante como um valor escalar, nulo ou matriz.LaudisNeo4jFormatterOGMFormatter que mapeia os tipos de cifra para os tipos de php, conforme explicado aqui.LaudisNeo4jFormatterSummarizedResultFormatter que decora qualquer formato e adiciona um extenso resumo de resultados.O construtor de clientes fornece uma maneira fácil de alterar o formatador:
$ client = Laudis Neo4j ClientBuilder:: create ()
-> withFormatter ( Laudis Neo4j Formatter SummarizedResultFormatter:: create ())
-> build ();
/**
* The client will now return a result, decorated with a summary.
*
* @var LaudisNeo4jDatabagsSummarizedResult $results
*/
$ summarisedResult = $ client -> run ( ' MATCH (x) RETURN x ' );
// The summary contains extensive information such as counters for changed values in the database,
// information on the database, potential notifications, timing, a (profiled) plan, the type of query
// and information on the server itself.
$ summary = $ summarisedResult -> getSummary ();
// The result is exactly the same as the default.
$ result = $ summarisedResult -> getResult (); Para usar um formatador personalizado, implemente o LaudisNeo4jContractsFormatterInterface e forneça ao usar o construtor de clientes.
A API do driver descrita aqui é o principal alvo do motorista. Por esse motivo, o cliente nada mais é do que um gerente de driver. O motorista cria sessões. Uma sessão executa consultas através de uma transação.
Devido a esse comportamento, você pode acessar cada conceito a partir do cliente assim:
use Laudis Neo4j ClientBuilder ;
// A builder is responsible for configuring the client on a high level.
$ builder = ClientBuilder:: create ();
// A client manages the drivers as configured by the builder.
$ client = $ builder -> build ();
// A driver manages connections and sessions.
$ driver = $ client -> getDriver ( ' default ' );
// A session manages transactions.
$ session = $ driver -> createSession ();
// A transaction is the atomic unit of the driver where are the cypher queries are chained.
$ transaction = $ session -> beginTransaction ();
// A transaction runs the actual queries
$ transaction -> run ( ' MATCH (x) RETURN count(x) ' );Se você precisar de controle completo, poderá controlar cada objeto com objetos de configuração personalizados.
Um cliente gerencia os drivers e rotula as consultas para os drivers corretos com base em aliases pré -configurados.
O objeto de driver é o backbone seguro para rosca que dá acesso ao neo4J. Ele possui um pool de conexões e pode gerar sessões para realizar o trabalho.
use Laudis Neo4j Basic Driver ;
use Laudis Neo4j Databags DriverConfiguration ;
$ driver = Driver:: create (
uri: ' neo4j://user:mypassword@Localhost:7687 ' ,
configuration: DriverConfiguration:: create ()-> withUserAgent ( ' MyApp/1.0.0 ' )
);As sessões são recipientes leves para sequências de transações causalmente encadeadas. Eles emprestam conexões do pool de conexões, conforme necessário e transações em cadeia usando marcadores .
use Laudis Neo4j Databags SessionConfiguration ;
use Laudis Neo4j Enum AccessMode ;
$ session = $ driver -> createSession (SessionConfiguration:: create ()
-> withDatabase ( ' my-database ' )
-> withAccessMode (AccessMode:: READ ())
);As transações são unidades atômicas de trabalho que podem conter uma ou mais consultas . Cada transação está vinculada a uma única conexão e é representada na cadeia causal por um marcador .
As consultas são unidades executáveis nas transações e consistem em uma sequência de cifra e um conjunto de parâmetros com chave. Cada consulta produz um resultado que pode conter zero ou mais registros .
Um resultado contém a saída de uma consulta , composta por metadados do cabeçalho, registros de conteúdo e metadados de resumo. No Neo4J 4.0 e acima, os aplicativos têm controle sobre o fluxo de dados de resultados.
O esquema de URL é a maneira mais fácil de configurar o motorista.
Formato de configuração:
'<scheme>://<user>:<password>@<host>:<port>?database=<database>'
Configuração padrão:
bolt://localhost:7687?database=neo4j
Esta biblioteca suporta três drivers: Bolt, HTTP e Neo4J. A parte do esquema do URL determina o motorista.
| motorista | esquema | Certificado válido | Certificado autoassinado | função |
|---|---|---|---|---|
| neo4j | neo4j | neo4j+s | neo4j+ssc | Roteamento do lado do cliente sobre o parafuso |
| parafuso | parafuso | parafuso+s | parafuso+ssc | Servidor único sobre o parafuso |
| http | http | https | configurado através da implementação do cliente PSR | Servidor único sobre http |
Um driver, sessão e transação podem ser configurados usando objetos de configuração. Uma visão geral das opções de configuração pode ser encontrada aqui:
| nome | conceito | descrição | aula |
|---|---|---|---|
| agente de usuário | motorista | O agente do usuário usado para identificar o cliente no servidor NEO4J. | DriverConfiguration |
| Ligações HTTP PSR | motorista | A implementação relevante do PSR usada pelo driver ao usar o protocolo HTTP. | DriverConfiguration |
| banco de dados | sessão | O banco de dados a se conectar. | SessionConfiguration |
| Tamanho da busca | sessão | A quantidade de linhas para buscar de uma só vez. | SessionConfiguration |
| modo de acesso | sessão | O modo padrão ao acessar o servidor. | SessionConfiguration |
| Marcadores | sessão | Os favoritos usados na sessão. (experimental) | SessionConfiguration |
| Metadados | transação | Os metadados utilizados durante a transação. (experimental) | TransactionConfiguration |
| tempo esgotado | transação | A quantidade máxima de tempo antes de chegar a ser dividida. | TransactionConfiguration |
Exemplo de código:
use Laudis Neo4j Databags DriverConfiguration ;
use Laudis Neo4j Databags SessionConfiguration ;
use Laudis Neo4j Databags TransactionConfiguration ;
$ client = Laudis Neo4j ClientBuilder:: create ()
-> withDefaultDriverConfiguration (DriverConfiguration:: default ()-> withUserAgent ( ' MyApp/1.0.0 ' ))
-> withDefaultSessionConfiguration (SessionConfiguration:: default ()-> withDatabase ( ' app-database ' ))
-> withDefaultTransactionConfiguration (TransactionConfiguration:: default ()-> withTimeout ( 5.0 ))
-> build ();
// The client will run the query on a driver with the provided config,
// which spawns a session with the provided session config
// and runs the query in a transaction with the provided transaction config
$ client -> run ( ' MATCH (x) RETURN count(x) AS count ' );
// More granular control can be achieved by requesting the concepts yourself:
$ tsx = $ client -> getDriver ( ' default ' )
-> createSession (SessionConfiguration:: default ()-> withDatabase ( ' management-database ' ))
-> beginTransaction ( null , TransactionConfiguration:: default ()-> withTimeout ( 200 ));
$ tsx -> run ( ' SOME REALLY LONG MANAGEMENT QUERY ' );
$ tsx -> commit ();
