# Class SuperContainer

This class is a PHP API for interation with SuperContainer. This provides an easy-to-use object-oriented API for uploading, downloading, and deleting files from a SuperContainer server, in addition to getting metadata about files on a SuperContainer server. This is especially useful for custom web publishing (CWP) FileMaker solutions using PHP.

### Requirements

This requires that PHP be built with curl library support enabled.

There are no other dependencies.

### Example Usage

To use the SuperContainer lib, you first create a SuperContainer object:
`<?php
$sc = new SuperContainer('http://server.mycompany.com:8020/SuperContainer/Files');
?>`
Then you can use this object to upload a file:
`<?php
$sc->upload('uploads/12345', '/path/to/my/local-file.txt');
?>`
Get metadata about an uploaded file:
`<?php
$infoArray = $sc->getInfo('uploads/12345');
$fileName = $infoArray['name'];
$fileSize = $infoArray['size'];
$uploadDate = $infoArray['date'];
?>`
Download the SuperContainer file to your local drive:
`<?php
$localPath = $sc->download('uploads/12345', '/tmp');
?>`
Or delete an uploaded file:
`<?php
$sc->delete('uploads/12345');
?>`

To handle file uploads in PHP, move the uploaded file using the `move_uploaded_file` function, then the `upload` function of SuperContainer. The following example illustrates handling a file upload, and better error handling.

`<?php
$SC_BASE_URL = 'http://server.mycompany.com:8020/SuperContainer/Files';
$sc = new SuperContainer($SC_BASE_URL);
if ($sc->getError()) die('Could not connect to SuperContainer server: ' . $sc->getError());
$uploadedFile = sys_get_temp_dir() . '/' . $_FILES['upload']['name'];
move_uploaded_file($_FILES['upload']['tmp_name'], $uploadedFile)
or die("Could not move uploaded file to $uploadedFile");
$folderPath = 'uploads/12345';
$sc->upload($folderPath, $uploadedFile)
or die("Could not upload $uploadedFile to $folderPath: " . $sc->getError());
?>`

## Constructor

`

### SuperContainer

SuperContainer (string $baseUrl [, string $user [, string $password]])`
  Constructor which accepts a baseUrl, optional username, optional password.

  Note that values cannot be returned from a constructor, therefore it is difficult to validate the return value. To verify that the `SuperContainer` object was created correctly, you should call `getError()` immediately after creating the new object.

  Parameters:
  `$baseUrl -` The Base URL of your SuperContainer server, e.g. `http://server.mycompany.com:8020/SuperContainer/Files`
  `$user -` Optional username, only required if your SuperContainer server is password protected
  `$password -` Optional password, only required if your SuperContainer server is password protected

## Methods

`

### getVersion

getVersion ()`
  Returns the version number of the PHP api.

`

### getError

string getError ()`
  Gets the last SuperContainer error message. Use this to log errors or display additional information to users.

`

### upload

boolean upload (string $folderPath, string $data)`
  Upload a file to the SuperContainer server. Returns `true` if the upload was successful, false if not.
  Parameters:
  `$folderPath -` The unique identifier for a supercontainer file.
  `$data -` local path to the file to upload.

`

### download

string download (string $folderPath, string $destination)`
  Download a file from the SuperContainer server to the local filesystem. This returns the final path of the downloaded file, or `false` if the download failed, or `''` if there was no file to download at the specified `folderPath`.

  Note: If `$destination` is a directory, the downloaded file will be given the same name it had on the SuperContainer server. If `$destination` is not a directory, the file will be downloaded to `$destination` without altering the path at all. Note that the parent directory must exist for this operation to complete successfully.

  Parameters:
  `$folderPath -` The unique identifier for the supercontainer file to download
  `$destination -` The local destination path to download the file to

`

### getInfo

array getInfo (string $folderPath)`
  Retrieve information about a SuperContainer file without actually download it. This returns an associative array with the following keys:
  name
    The name of the file
  size
    The size in bytes of the file
  date
    The date the file was uploaded to SuperContainer (use `strtotime()` to convert this to a timestamp)

  If there is no file at the given `folderPath`, an empty array is returned. However, calling `getError` will return an empty string.

  Parameters:
  `$folderPath -` The unique identifier for the supercontainer file to download

`

### delete

boolean delete (string $folderPath)`
  Delete a file from the SuperContainer server. Returns `true` if the delete operation was successful, or there was no file to delete. Otherwise, returns `false`.
  Parameters:
  `$folderPath -` The unique identifier for the supercontainer file to download