Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
messages
tests
util
xmysqlnd
.gitignore
CREDITS
LICENSE
Makefile.frag
README
config-win.h
config.m4
config.w32
examples.php
mysql_xdevapi.def
mysqlnd_api.h
mysqlx_base_result.cc
mysqlx_base_result.h
mysqlx_class_properties.cc
mysqlx_class_properties.h
mysqlx_collection.cc
mysqlx_collection.h
mysqlx_collection__add.cc
mysqlx_collection__add.h
mysqlx_collection__find.cc
mysqlx_collection__find.h
mysqlx_collection__modify.cc
mysqlx_collection__modify.h
mysqlx_collection__remove.cc
mysqlx_collection__remove.h
mysqlx_collection_index.cc
mysqlx_collection_index.h
mysqlx_column_result.cc
mysqlx_column_result.h
mysqlx_crud_operation_bindable.cc
mysqlx_crud_operation_bindable.h
mysqlx_crud_operation_limitable.cc
mysqlx_crud_operation_limitable.h
mysqlx_crud_operation_skippable.cc
mysqlx_crud_operation_skippable.h
mysqlx_crud_operation_sortable.cc
mysqlx_crud_operation_sortable.h
mysqlx_database_object.cc
mysqlx_database_object.h
mysqlx_doc_result.cc
mysqlx_doc_result.h
mysqlx_doc_result_iterator.cc
mysqlx_doc_result_iterator.h
mysqlx_driver.cc
mysqlx_driver.h
mysqlx_enum_n_def.h
mysqlx_exception.cc
mysqlx_exception.h
mysqlx_executable.cc
mysqlx_executable.h
mysqlx_execution_status.cc
mysqlx_execution_status.h
mysqlx_expression.cc
mysqlx_expression.h
mysqlx_field_metadata.cc
mysqlx_field_metadata.h
mysqlx_object.cc
mysqlx_object.h
mysqlx_result.cc
mysqlx_result.h
mysqlx_result_iterator.cc
mysqlx_result_iterator.h
mysqlx_row_result.cc
mysqlx_row_result.h
mysqlx_row_result_iterator.cc
mysqlx_row_result_iterator.h
mysqlx_schema.cc
mysqlx_schema.h
mysqlx_schema_object.cc
mysqlx_schema_object.h
mysqlx_session.cc
mysqlx_session.h
mysqlx_sql_statement.cc
mysqlx_sql_statement.h
mysqlx_sql_statement_result.cc
mysqlx_sql_statement_result.h
mysqlx_sql_statement_result_iterator.cc
mysqlx_sql_statement_result_iterator.h
mysqlx_table.cc
mysqlx_table.h
mysqlx_table__delete.cc
mysqlx_table__delete.h
mysqlx_table__insert.cc
mysqlx_table__insert.h
mysqlx_table__select.cc
mysqlx_table__select.h
mysqlx_table__update.cc
mysqlx_table__update.h
mysqlx_warning.cc
mysqlx_warning.h
mysqlx_x_session.cc
mysqlx_x_session.h
package.xml
php_api.h
php_mysql_xdevapi.h
php_mysqlx.cc
php_mysqlx.h
php_mysqlx_ex.cc
php_mysqlx_ex.h
product_data.txt
protobuf_api.h

README

MySQL X DevAPI for PHP
======================

This PHP Extension provides MySQL's X DevAPI. The X DevAPI is a new CRUD-style
API for accessing MySQL as a Document Store. It is based on the MySQL 8's X
protocol and unifies JSON document and table access, and it includes SQL
support. The API features a popular fluent interface style and aims to be
particularly easy to use yet powerful. The X DevAPI sees wide cross product
support. Developers can use the same syntax and rely on the existence of
virtually the same feature set in may products they work with on a day to
day basis.

The X DevAPI combines elements of the relational database model with elements
of storing JSON documents. Working with schemaless data serialized in JSON has
become very popular in recent years. Schema flexibility allows data-first
development models. For example, application developers do not need to define
the very details of the data to be stored before it can be saved, customers
can model applications using an iterative approach, defining the details along
the way when they work with the developers. In other areas a mode-first
development model may fit the brief better. The X DevAPI supports both working
with schemaful relational tables and schemaless collections of JSON documents.

The X DevAPI abstracts the notion of a connection to that of a session. A
session encapsulates physical connections. This concept is crucial for
any environment where the creation, selection and life span of a physical
connection shall not be a concern of the application developer.

To learn more about the details of the X DevAPI refer to the documentation on
http://dev.mysql.com/doc/x-devapi-userguide/en/

To learn more about MySQL as a Document Store efer to documentation on
http://dev.mysql.com/doc/refman/8.0/en/document-store.html


Installation
------------

This extension depends on PHP 7.1 or newer. For general installation instructions
for PHP extensions see http://php.net/install.pecl

In addition to PHP's dependencies, Google's Protocol Buffer and boost libraries
are required. On any Linux-based systems a package called libprotobuf-dev or
similar is required.

Further hints for installing this module:

0) configure/build
The extension name is "mysql-xdevapi", you enable it with
"--enable-mysql-xdevapi", for the moment only phpize/pecl build mode
is officially supported.

Required 3rdParty libs (boost, protobuf) may be configured with following options:
--with-boost[=DIR]
--with-protobuf[=DIR]

They may be pointed out with below environment variables too:
- MYSQL_XDEVAPI_PROTOBUF_ROOT to point out google protobuf root
- MYSQL_XDEVAPI_BOOST_ROOT to point out boost libraries

And on Windows also with configure options: --with-extra-includes --with-extra-libs

1) Build on Windows
It is recommended to prepare environment and build mysql_xdevapi extension according to:
https://wiki.php.net/internals/windows/stepbystepbuild (older SDK, PHP-7.1 only)
https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2 (PHP-7.1 or newer)

2) Boost
Only headers are needed, no boost binaries required.

3) Google Protocol Buffers on Windows
On Windows depending on used run-times the static library with Multi-Threaded DLL
runtime may be needed. To prepare such library on your own following options should
be applied:
-Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF

4) Google Protocol Buffers / protocol compiler (protoc)
In configuration of build there is no extra option to set additional dir with binaries,
so ensure that proper 'protoc' is available on PATH while building. It is especially
important in case of usage PHP SDK on Windows - its batch scripts may overwrite
environment.

5) Bison
Ensure that proper version of Bison is on path while building.

If you build on Windows (especially with older SDK - see point 1.) it is strongly
recommended to use the one delivered with chosen PHP SDK, else (in case of improper
bison.exe version) following error may be met:

c:\php-sdk\phpdev\vc14\x86\connector-php-7.1.0\zend\zend_globals_macros.h(39):
	error C2375: 'zendparse': redefinition; different linkage
Zend/zend_language_parser.h(214): note: see declaration of 'zendparse'

Besides, batch scripts from PHP SDK on Windows may overwrite environment.



Supported X DevAPI features
---------------------------
- collections API - add, find, modify, remove
- collection single doc API - getOne, replaceOne, addOrReplaceOne, removeOne
- new document _id generation
- authentication modes: MYSQL41, PLAIN, EXTERNAL, SHA256_MEM
- table API - insert, select, update, delete
- row locking for Collection.Find / Table.Select, also modes NOWAIT and SKIP LOCKED
- collection / table - getName, existsInDatabase, count
- collection index - create, drop
- resultsets / multi-resultsets
- getCollection(s) / getTable(s) / getCollectionAsTable
- drop schema / collection

For a simple use cases see examples.php or tests/*.phpt

License
-------
Copyright (c) 2006-2018 The PHP Group

This source file is subject to version 3.01 of the PHP license,
that is bundled with this package in the file LICENSE, and is
available through the world-wide-web at the following url:
http://www.php.net/license/3_01.txt
If you did not receive a copy of the PHP license and are unable to
obtain it through the world-wide-web, please send a note to
license@php.net so we can mail you a copy immediately.