Introduction

Personyze API server is SOAP server that resides on endpoint https://personyze.com/site/service/service/ (can be used through http:// as well). Currently Personyze offers the following SOAP services:

To use these services from PHP scripts, we provide convenience SOAP-client library (it is not recommended to access services directly).

Download client library

To set up, unzip the library to any location on your web server (where you usually put PHP libraries). The library has only one class that you should know. All the actions with remote Personyze services are done through it. This class is called “Personyze_Table” and it’s located in file “Personyze_Table.class.php”.

Usage is as follows:

<?php

// Example of showing all actions from account.

require_once 'Personyze/Personyze_Table.class.php';

$server_id = 1; // Account ID.
$api_key = 'my_key'; // Account key.

$table = new Personyze_Table($server_id, $api_key, 'actions');

var_dump($table->select()); // show all actions

Explanation:

  1. Do a require_once providing valid path. We assume that the library was installed to directory named “Personyze”.
  2. Set server_id and api_key received from Personyze.
  3. Create $table representing link to remote service. The third argument to constructor is service name: ‘actions’ in this example.
  4. Call method “select()” and print results.

Interface to each service is like to a table in database. Most manipulations with remote objects are done through the following methods:

All the services provide these methods. Some services also provide additional methods. Details specific to each service are covered in the following sections:

Method select().

array select(mixed $columns=null, mixed $where=null, mixed $order_by=null, boolean $order_by_desc=false, integer $from=0, integer $limit=0, boolean $calc_count_rows=false, boolean $calc_accurate=false)

Selects array of records.

Argument Description Default value Examples
columns What columns to select from the table. Each table has it’s own specific set of columns that can be selected. E.g. if the table is actions, the columns can be: “name”, “action_js_id”, and so on.This argument can be:

  • null – select all available columns
  • string – list of column expressions delimited by comma
  • array – array of column expressions where each element in array represents single column expression
null
  • “name, comments”
  • array(“name”, “comments”)
  • “Concat(‘Name: ‘, name, ‘; Comments: ‘, comments), Length(comments) AS com_len”
where The “WHERE” condition. Only records that pass the condition are returned.This argument can be:

  • null – select all records
  • string – a column expression
  • array – array of record IDs to return. If empty array, will return nothing. Only existing records are returned.
null
  • “NOT is_pagegroup AND Length(name)>0”
  • array(1, 2, 3)
order_by How to sort resulting records.This argument can be:

  • null – default order
  • string – column expressions delimited by comma. Will first sort by first listed expression. Then records where first expression was the same will be sorted by the second expression, etc. At end of each expression there can appear word “DESC”, that means descendant order.
  • array – array of column expressions where each element in array represents single column expression
null
  • “last_name, first_name”
  • array(“last_name”, “first_name”)
order_by_desc Whether to reverse sorting order. This argument is interpreted as boolean. false true
from Return results (matched “where” condition) starting from this record number. First this number of results will be ignored. This argument is interpreted as integer. false true
limit Return no more than this number of resulting records. Further results will be ignored. This argument is interpreted as integer. false true
calc_count_rows Whether to count how many results match “where” condition. If “from” or “limit” were specified, this number can be greater than number of returned results. The counted number can be fetched later with last_count() method. This argument, in conjunction with “from” and “limit” allows to split results to pages, knowing how many pages there are in total. This argument is interpreted as boolean. false true
calc_accurate Whether to allow approximate count of matched records. If is set to false (the default), the query can be run faster. The result is always accurate (despite this argument) on the last page in pagination. The last page is detected as “approx_rows_count <= from + limit”. Therefore pagination mechanism will still operate with calc_accurate set to false. This argument is interpreted as boolean. false true

Result is array of records. Each record is associative array of “column_name” => “column_value”. The column_value is usually string, but some tables can return arrays for certain columns.

Method last_count().

integer last_count()

Get number of matched results from latest call to select() with calc_count_rows set to true.

Method select_row().

array select_row(integer $id, mixed $columns=null)

Fetch record having specified ID. If there is no such record, exception will be thrown.

Argument Description Default value Examples
id The ID of desired record. (mandatory) 10
columns The same meaning as in select(). null
  • “name, comments”
  • array(“name”, “comments”)
  • “Concat(‘Name: ‘, name, ‘; Comments: ‘, comments), Length(comments) AS com_len”

Result is single record as associative array of “column_name” => “column_value”. The column_value is usually string, but some tables can return arrays for certain columns.

Method insert().

integer insert(array $columns)

Insert new record to the table.

Argument Description Default value Examples
columns Associative array of “column_name” => “column_value”. The column_value is usually expected to be string, but some tables require arrays for certain columns. (mandatory) array(‘name’=>’John’, ’email’=>’john.doe@gmail.com’)

Returns the ID of just inserted record.

Method last_insert_id().

integer last_insert_id()

Returns ID of most recently inserted record.

Method update_row().

void update_row(integer $id, array $columns)

Update a single row having specified ID. If there is no such row, exception will be thrown.

Argument Description Default value Examples
id The ID of desired record. (mandatory) 10
columns Associative array of “column_name” => “column_value”. The column_value is usually expected to be string, but some tables require arrays for certain columns. Only specified columns of the record will be modified. Columns that are not in this array will remain intact. (mandatory) array(‘name’=>’John’, ’email’=>’john.doe@gmail.com’)

Method update().

void update(array $columns, mixed $where=null)

Update batch of records matching condition.

Argument Description Default value Examples
columns Associative array of “column_name” => “column_value”. The column_value is usually expected to be string, but some tables require arrays for certain columns. Only specified columns of all matched records will be modified. Columns that are not in this array will remain intact. (mandatory) array(‘name’=>’John’, ’email’=>’john.doe@gmail.com’) – sets ‘name’ to ‘John’ and ’email’ to ‘john.doe@gmail.com’ in each matched record.
where The “WHERE” condition.This argument can be:

  • null – update all records
  • string – a column expression
  • array – array of record IDs to update. If empty array, will do nothing. Only existing records are updated.
null
  • “NOT is_pagegroup AND Length(name)>0”
  • array(1, 2, 3)

Method delete_rows().

void delete_rows(array $ids, string $by_column=null)

Delete records having specified IDs. If some specified records are not found – does NOT throw exception.

Argument Description Default value Examples
ids Array of numeric IDs. If empty array – does nothing. (mandatory) array(1, 2, 3)
by_column If specified, must be a column name in the table (not column expression). By default assumed to be “id” in most tables (the primary key). “ids” is array of values to which “by_column” will be compared. It’s possible to search records by any other integer typed column. null
  • null
  • “id”
  • “parent_id”

Method delete().

void delete(mixed $where=null, boolean $can_delete_all=false)

Delete batch of records matching condition.

Argument Description Default value Examples
where The “WHERE” condition.This argument can be:

  • null – delete all records (must also set can_delete_all to true)
  • string – a column expression
  • array – array of record IDs to delete. If empty array, will do nothing.
null
  • “NOT is_pagegroup AND Length(name)>0”
  • array(1, 2, 3)
can_delete_all Whether to allow deleting all records from the table. If false, and where is null – throws exception. false true