core/xpdo/transport/xpdotransport.class.php

Show:

inherited

Classes
- \xPDOTransport

Table of Contents

Represents a transportable package of related data and other resources.

Package: xpdo
Subpackage: transport

\xPDOTransport
jump to top

Package: xpdo\transport

Represents xPDOObject and related data in a serialized format for exchange.

Constants

 
                PRESERVE_KEYS
                = 'preserve_keys'

 
                NATIVE_KEY
                = 'native_key'

 
                UNIQUE_KEY
                = 'unique_key'

 
                UPDATE_OBJECT
                = 'update_object'

 
                RESOLVE_FILES
                = 'resolve_files'

 
                RESOLVE_FILES_REMOVE
                = 'resolve_files_remove'

 
                RESOLVE_PHP
                = 'resolve_php'

 
                PACKAGE_ACTION
                = 'package_action'

 
                PACKAGE_STATE
                = 'package_state'

 
                RELATED_OBJECTS
                = 'related_objects'

 
                RELATED_OBJECT_ATTRIBUTES
                = 'related_object_attributes'

 
                MANIFEST_ATTRIBUTES
                = 'manifest-attributes'

 
                MANIFEST_VEHICLES
                = 'manifest-vehicles'

 
                MANIFEST_VERSION
                = 'manifest-version'

 
                PREEXISTING_MODE
                = 'preexisting_mode'

 
                INSTALL_FILES
                = 'install_files'

 
                UNINSTALL_FILES
                = 'uninstall_files'

 
                UNINSTALL_OBJECT
                = 'uninstall_object'

 
                ARCHIVE_WITH
                = 'archive_with'

 
                ABORT_INSTALL_ON_VEHICLE_FAIL
                = 'abort_install_on_vehicle_fail'

 
                PACKAGE_NAME
                = 'package_name'

 
                PACKAGE_VERSION
                = 'package_version'

integer 
                PRESERVE_PREEXISTING
                = 0

Indicates how pre-existing objects are treated on install/uninstall.

: integer

 
                REMOVE_PREEXISTING
                = 1

 
                RESTORE_PREEXISTING
                = 2

integer 
                STATE_UNPACKED
                = 0

Indicates the physical state of the package.

: integer

 
                STATE_PACKED
                = 1

 
                STATE_INSTALLED
                = 2

integer 
                ACTION_INSTALL
                = 0

Indicates an action that can be performed on the package.

: integer

 
                ACTION_UPGRADE
                = 1

 
                ACTION_UNINSTALL
                = 2

integer 
                ARCHIVE_WITH_DEFAULT
                = 0

Indicates which archiving tool to use for pack()'ing and unpack()'ing the transport.

: integer

 
                ARCHIVE_WITH_PCLZIP
                = 1

 
                ARCHIVE_WITH_ZIPARCHIVE
                = 2

Properties

array
                 $_preserved= 'array()'

An map of preserved objects from an install used by uninstall.

Default valuearray()Details

Type: array

array
                 $attributes= 'array ()'

Stores various attributes about the transport package.

Default valuearray ()Details

Type: array

string
                 $manifestVersion= ''1.1''

The current manifest version for this transport.

Default value'1.1'Details

Type: string

string
                 $name= 'null'

A unique name used to identify the package without the version.

Default valuenullDetails

Type: string

string
                 $path= 'null'

The physical location of the transport package.

Default valuenullDetails

Type: string

string
                 $signature= 'null'

A unique signature to identify the package.

Default valuenullDetails

Type: string
Access: public

integer
                 $state= 'null'

Indicates the state of the xPDOTransport instance.

Default valuenullDetails

Type: integer

array
                 $vehicles= 'array ()'

A map of object vehicles containing payloads of data for transport.

Default valuearray ()Details

Type: array

string
                 $version= 'null'

The package version, as a PHP-standardized version number string.

Default valuenullDetails

Type: string

\xPDO
                 $xpdo= 'null'

An {@link xPDO} reference controlling this transport instance.

Default valuenullDetails

Type: \xPDO
Access: public

Methods

__construct(
          \xPDO $xpdo, string $signature, string $path, array $options
              =
              array()
          )
        
        :
          void

Prepares and returns a new xPDOTransport instance.

Parameters

Name	Type	Description
$xpdo	\xPDO	&$xpdo The xPDO instance accessing this package.
$signature	string	The unique signature of the package.
$path	string	Valid path to the physical transport package.
$options	array	An optional array of attributes for constructing the instance.

_convertManifestVer1_0(
          array $manifestVehicles
          )
        
        :
          array

static

Converts older manifest vehicles to 1.0 format.

Parameters

Name	Type	Description
$manifestVehicles	array	A structure representing vehicles from a pre-1.0 manifest format.

Returns

Type	Description
array	Vehicle definition structures converted to 1.0 format.

Details

Access: private
Static

_convertManifestVer1_1(
          array $vehicles
          )
        
        :
          array

static

Converts 1.0 manifest vehicles to 1.1 format.

Parameters

Name	Type	Description
$vehicles	array	A structure representing vehicles from a pre-1.1 manifest format.

Returns

Type	Description
array	Vehicle definition structures converted to 1.1 format.

Details

Access: private
Static

_pack(
          \xPDO $xpdo, string $filename, string $path, string $source
          )
        
        :
          boolean

static

Pack the resources from path relative to source into an archive with filename.

Parameters

Name	Type	Description
$xpdo	\xPDO	&$xpdo A reference to an xPDO instance.
$filename	string	A valid zip archive filename.
$path	string	An absolute file system path location of the resources to pack.
$source	string	A relative portion of path to include in the archive.

Returns

Type	Description
boolean	True if packed successfully.

Details

Todo: Refactor this to be implemented in a service class external to xPDOTransport.
Uses: \compression.xPDOZip

_unpack(
          \xPDO $xpdo, string $from, string $to
          )
        
        :
          array | boolean

static

Unpack a zip archive to a specified location.

Parameters

Name	Type	Description
$xpdo	\xPDO	&$xpdo A reference to an xPDO instance.
$from	string	An absolute file system location to a valid zip archive.
$to	string	A file system location to extract the contents of the archive to.

Returns

Type	Description
array \| boolean	An array of unpacked resources or false on failure.

Details

Todo: Refactor this to be implemented in a service class external to xPDOTransport.
Uses: \compression.xPDOZip

compareSignature(
          \$signature1 $signature1, \$signature2 $signature2
          )
        
        :
          bool | int

static

Compares two package versions by signature.

Parameters

Name	Type	Description
$signature1	\$signature1	A package signature.
$signature2	\$signature2	Another package signature to compare.

Returns

Type	Description
bool \| int	Returns -1 if the first version is lower than the second, 0 if they are equal, and 1 if the second is lower if the package names in the provided signatures are equal; otherwise returns false.

Details

Static

get(
          string $objFile, array $options
              =
              array ()
          )
        
        :
          \xPDOVehicle

Get an {@link xPDOVehicle} instance from an unpacked transport package.

Parameters

Name	Type	Description
$objFile	string	Full path to a payload file to import. The payload file, when included must return a valid {@link xPDOVehicle::$payload}.
$options	array	An array of options to be applied when getting the object.

Returns

Type	Description
\xPDOVehicle	The vehicle represented in the file.

getAttribute(
          string $key
          )
        
        :
          mixed

Get an attribute of the package manifest.

Parameters

Name	Type	Description
$key	string	The key of the attribute to retrieve.

Returns

Type	Description
mixed	The value of the attribute or null if it is not set.

install(
          array $options
              =
              array ()
          )
        
        :
          boolean

Install vehicles in the package into the sponsor {@link xPDO} instance.

Parameters

Name	Type	Description
$options	array	Install options to be applied to the process.

Returns

Type	Description
boolean	true if the vehicles were successfully installed.

loadPreserved(
          
          )
        
        :
          array

Load preserved objects from the previous install().

Returns

Type	Description
array	An array of preserved objects, or an empty array.

manifestVersion(
          array $manifest
          )
        
        :
          string

static

Returns the structure version of the given manifest array.

Parameters

Name	Type	Description
$manifest	array	A valid xPDOTransport manifest array.

Returns

Type	Description
string	Version string of the manifest structure.

Details

Static

pack(
          
          )
        
        :
          boolean

Pack the {@link xPDOTransport} instance in preparation for distribution.

Returns

Type	Description
boolean	Indicates if the transport was packed successfully.

parseSignature(
          string $signature
          )
        
        :
          array

static

Parse the name and version from a package signature.

Parameters

Name	Type	Description
$signature	string	The package signature to parse.

Returns

Type	Description
array	An array with two elements containing the name and version respectively.

Details

Static

put(
          mixed $artifact, array $attributes
              =
              array ()
          )
        
        :
          void

Wrap artifact with an {@link xPDOVehicle} and register in the transport.

Parameters

Name	Type	Description
$artifact	mixed	An artifact to load into the transport.
$attributes	array	A set of attributes related to the artifact; these can be anything from rules describing how to pack or unpack the artifact, or any other data that might be useful when dealing with a transportable artifact.

registerVehicle(
          \xPDOVehicle $vehicle
          )
        
        :
          void

Parameters

Name	Type	Description
$vehicle	\xPDOVehicle	&$vehicle A reference to the vehicle being registered.

retrieve(
           $xpdo,  $source,  $target,  $state
              =
              xPDOTransport::STATE_PACKED
          )
        
        :
          void

static

Get an existing {@link xPDOTransport} instance.

Parameters

Name	Type	Description
$xpdo
$source
$target
$state

setAttribute(
          string $key, mixed $value
          )
        
        :
          void

Set an attribute of the package manifest.

Parameters

Name	Type	Description
$key	string	The key identifying the attribute to set.
$value	mixed	The value to set the attribute to.

store(
          mixed $location
          )
        
        :
          void

Store the package to a specified resource location.

Parameters

Name	Type	Description
$location	mixed	The location to store the package.

Details

Todo: Implement ability to store a package to a specified location, supporting various transport methods.

uninstall(
          array $options
              =
              array ()
          )
        
        :
          boolean

Uninstall vehicles in the package from the sponsor {@link xPDO} instance.

Parameters

Name	Type	Description
$options	array	Uninstall options to be applied to the process.

Returns

Type	Description
boolean	true if the vehicles were successfully uninstalled.

unpack(
          \xPDO $xpdo, string $from, string $to, integer $state
              =
              xPDOTransport::STATE_PACKED
          )
        
        :
          array

static

Unpack the package to prepare for installation and return a manifest.

Parameters

Name	Type	Description
$xpdo	\xPDO	&$xpdo A reference to an xPDO instance.
$from	string	Filename of the archive containing the transport package.
$to	string	The root path where the contents of the archive should be extracted. This path must be writable by the user executing the PHP process on the server.
$state	integer	The current state of the package, i.e. packed or unpacked.

Returns

Type	Description
array	The manifest which is included after successful extraction.

writeManifest(
          
          )
        
        :
          boolean

Write the package manifest file.

Returns

Type	Description
boolean	Indicates if the manifest was successfully written.

writePreserved(
          
          )
        
        :
          boolean

Write objects preserved during install() to file for use by uninstall().

Returns

Type	Description
boolean	Indicates if the preserved file was successfully written.

core/xpdo/transport/xpdotransport.class.php

\xPDOTransportjump to top

Constants

Properties

Methods

\xPDOTransport
jump to top