php-cloudfiles
[ class tree: php-cloudfiles ] [ index: php-cloudfiles ] [ all elements ]
Packages:
php-cloudfiles
php-cloudfiles-exceptions
php-cloudfiles-http


Files:
cloudfiles.php

Classes:
CF_Authentication
CF_Connection
CF_Container
CF_Object

Class: CF_Object

Source Location: /cloudfiles.php

Class Overview




Object operations









        




Variables







Methods
























Class Details



[line 1883]

Object operations

An Object is analogous to a file on a conventional filesystem. You can  read data from, or write data to your Objects. You can also associate  arbitrary metadata with them.





[ Top ]







Class Variables



	
	

	
$container = 

	
[line 1885]

  



Tags:





  

    access:  public
  






  

	

  

    

      Type:  
      mixed
    

      

	



	
[ Top ]


	
	

	
$content_length = 

	
[line 1889]

  



Tags:





  

    access:  public
  






  

	

  

    

      Type:  
      mixed
    

      

	



	
[ Top ]


	
	

	
$content_type = 

	
[line 1888]

  



Tags:





  

    access:  public
  






  

	

  

    

      Type:  
      mixed
    

      

	



	
[ Top ]


	
	

	
$headers = 

	
[line 1891]

  



Tags:





  

    access:  public
  






  

	

  

    

      Type:  
      mixed
    

      

	



	
[ Top ]


	
	

	
$last_modified = 

	
[line 1887]

  



Tags:





  

    access:  public
  






  

	

  

    

      Type:  
      mixed
    

      

	



	
[ Top ]


	
	

	
$manifest = 

	
[line 1892]

  



Tags:





  

    access:  public
  






  

	

  

    

      Type:  
      mixed
    

      

	



	
[ Top ]


	
	

	
$metadata = 

	
[line 1890]

  



Tags:





  

    access:  public
  






  

	

  

    

      Type:  
      mixed
    

      

	



	
[ Top ]


	
	

	
$name = 

	
[line 1886]

  



Tags:





  

    access:  public
  






  

	

  

    

      Type:  
      mixed
    

      

	



	
[ Top ]










Class Methods




  

	
	
constructor __construct [line 1902]

	

    

    

		CF_Object __construct(

&$container, string
$name, [boolean
$force_exists = False], [
$dohead = True], obj
$container)
    

    


	
		Class constructor





	
        
Parameters:

    

    

          

        obj  
        $container  
        CF_Container instance
      

          

        string  
        $name  
        name of Object
      

          

        boolean  
        $force_exists  
        if set, throw an error if Object doesn't exist
      

          

          
        &$container  
        
      

          

          
        $dohead  
        
      

        

    


        
[ Top ]

  

  

	
	
method compute_md5sum [line 2522]

	

    

    

		string compute_md5sum(

&$data, filename|obj|string
$data)
    

    


	
		Compute the MD5 checksum

Calculate the MD5 checksum on either a PHP resource or data.  The argument  may either be a local filename, open resource for reading, or a string.
WARNING: if you are uploading a big file over a stream  it could get very slow to compute the md5 you probably want to  set the $verify parameter to False in the write() method and  compute yourself the md5 before if you have it.





Tags:





  

    return:  MD5 checksum hexidecimal string
  









	
        
Parameters:

    

    

          

        filename|obj|string  
        $data  
        filename, open resource, or string
      

          

          
        &$data  
        
      

        

    


        
[ Top ]

  

  

	
	
method getETag [line 2503]

	

    

    

		string getETag(
)
    

    


	
		Object's MD5 checksum

Accessor method for reading Object's private ETag attribute.





Tags:





  

    return:  MD5 checksum hexidecimal string
  









	
        
[ Top ]

  

  

	
	
method load_from_filename [line 2393]

	

    

    

		boolean load_from_filename(
string
$filename, [boolean
$verify = True])
    

    


	
		Upload Object data from local filename

This is a convenience function to upload the data from a local file.  A  True value for $verify will cause the method to compute the Object's MD5  checksum prior to uploading.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  $my_docs = $conn->get_container("documents");
    5. 

  5.  $doc = $my_docs->get_object("README");
    6. 

  6.  
    7. 

  7.  # Upload my local README's content
    8. 

  8.  #
    9. 

  9.  $doc->load_from_filename("/home/ej/cloudfiles/readme");
    10. 






Tags:





  

    return:  True if data uploaded successfully
  

  

    throws:  SyntaxException missing required parameters
  

  

    throws:  BadContentTypeException if no Content-Type was/could be set
  

  

    throws:  MisMatchedChecksumException $verify is set and checksums unequal
  

  

    throws:  InvalidResponseException unexpected response
  

  

    throws:  IOException error opening file
  









	
        
Parameters:

    

    

          

        string  
        $filename  
        full path to local file
      

          

        boolean  
        $verify  
        enable local/remote MD5 checksum validation
      

        

    


        
[ Top ]

  

  

	
	
method public_ssl_uri [line 2052]

	

    

    

		string public_ssl_uri(
)
    

    


	
		String representation of the Object's public SSL URI

A string representing the Object's public SSL URI assuming that it's  parent Container is CDN-enabled.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  # Print out the Object's CDN SSL URI (if it has one) in an HTML img-tag
    5. 

  5.  #
    6. 

  6.  print "<img src='$pic->public_ssl_uri()' />\n";
    7. 






Tags:





  

    return:  Object's public SSL URI or NULL
  









	
        
[ Top ]

  

  

	
	
method public_streaming_uri [line 2077]

	

    

    

		string public_streaming_uri(
)
    

    


	
		String representation of the Object's public Streaming URI

A string representing the Object's public Streaming URI assuming that it's  parent Container is CDN-enabled.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  # Print out the Object's CDN Streaming URI (if it has one) in an HTML img-tag
    5. 

  5.  #
    6. 

  6.  print "<img src='$pic->public_streaming_uri()' />\n";
    7. 






Tags:





  

    return:  Object's public Streaming URI or NULL
  









	
        
[ Top ]

  

  

	
	
method public_uri [line 2026]

	

    

    

		string public_uri(
)
    

    


	
		String representation of the Object's public URI

A string representing the Object's public URI assuming that it's  parent Container is CDN-enabled.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  # Print out the Object's CDN URI (if it has one) in an HTML img-tag
    5. 

  5.  #
    6. 

  6.  print "<img src='$pic->public_uri()' />\n";
    7. 






Tags:





  

    return:  Object's public URI or NULL
  









	
        
[ Top ]

  

  

	
	
method purge_from_cdn [line 2466]

	

    

    

		boolean purge_from_cdn(
[
$email = null])
    

    


	
		Purge this Object from CDN Cache.

Example:





Tags:





  

    return:  True if successful
  

  

    throws:  CDNNotEnabledException if CDN Is not enabled on this connection
  

  

    throws:  InvalidResponseException if the response expected is not returned
  









	
        
Parameters:

    

    

          

          
        $email  
        
      

        

    


        
[ Top ]

  

  

	
	
method read [line 2113]

	

    

    

		string read(
[array
$hdrs = array()])
    

    


	
		Read the remote Object's data

Returns the Object's data.  This is useful for smaller Objects such  as images or office documents.  Object's with larger content should use  the stream() method below.
Pass in $hdrs array to set specific custom HTTP headers such as  If-Match, If-None-Match, If-Modified-Since, Range, etc.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  $my_docs = $conn->get_container("documents");
    5. 

  5.  $doc = $my_docs->get_object("README");
    6. 

  6.  $data = $doc->read(); # read image content into a string variable
    7. 

  7.  print $data;
    8. 

  8.  
    9. 

  9.  # Or see stream() below for a different example.
    10. 

  10.  #
    11. 






Tags:





  

    return:  Object's data
  

  

    throws:  InvalidResponseException unexpected response
  









	
        
Parameters:

    

    

          

        array  
        $hdrs  
        user-defined headers (Range, If-Match, etc.)
      

        

    


        
[ Top ]

  

  

	
	
method save_to_filename [line 2438]

	

    

    

		boolean save_to_filename(
string
$filename)
    

    


	
		Save Object's data to local filename

Given a local filename, the Object's data will be written to the newly  created file.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  # Whoops!  I deleted my local README, let me download/save it
    5. 

  5.  #
    6. 

  6.  $my_docs = $conn->get_container("documents");
    7. 

  7.  $doc = $my_docs->get_object("README");
    8. 

  8.  
    9. 

  9.  $doc->save_to_filename("/home/ej/cloudfiles/readme.restored");
    10. 






Tags:





  

    return:  True if successful
  

  

    throws:  IOException error opening file
  

  

    throws:  InvalidResponseException unexpected response
  









	
        
Parameters:

    

    

          

        string  
        $filename  
        name of local file to write data to
      

        

    


        
[ Top ]

  

  

	
	
method set_etag [line 2490]

	

    

    

		void set_etag(
string
$etag)
    

    


	
		Set Object's MD5 checksum

Manually set the Object's ETag.  Including the ETag is mandatory for  Cloud Files to perform end-to-end verification.  Omitting the ETag forces  the user to handle any data integrity checks.





	
        
Parameters:

    

    

          

        string  
        $etag  
        MD5 checksum hexidecimal string
      

        

    


        
[ Top ]

  

  

	
	
method stream [line 2170]

	

    

    

		string stream(

&$fp, [array
$hdrs = array()], resource
$fp)
    

    


	
		Streaming read of Object's data

Given an open PHP resource (see PHP's fopen() method), fetch the Object's  data and write it to the open resource handle.  This is useful for  streaming an Object's content to the browser (videos, images) or for  fetching content to a local file.
Pass in $hdrs array to set specific custom HTTP headers such as  If-Match, If-None-Match, If-Modified-Since, Range, etc.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  # Assuming this is a web script to display the README to the
    5. 

  5.  # user's browser:
    6. 

  6.  #
    7. 

  7.  <?php
    8. 

  8.  // grab README from storage system
    9. 

  9.  //
    10. 

  10.  $my_docs = $conn->get_container("documents");
    11. 

  11.  $doc = $my_docs->get_object("README");
    12. 

  12.  
    13. 

  13.  // Hand it back to user's browser with appropriate content-type
    14. 

  14.  //
    15. 

  15.  header("Content-Type: " . $doc->content_type);
    16. 

  16.  $output = fopen("php://output", "w");
    17. 

  17.  $doc->stream($output); # stream object content to PHP's output buffer
    18. 

  18.  fclose($output);
    19. 

  19.  ?>
    20. 

  20.  
    21. 

  21.  # See read() above for a more simple example.
    22. 

  22.  #
    23. 






Tags:





  

    return:  Object's data
  

  

    throws:  InvalidResponseException unexpected response
  









	
        
Parameters:

    

    

          

        resource  
        $fp  
        open resource for writing data to
      

          

        array  
        $hdrs  
        user-defined headers (Range, If-Match, etc.)
      

          

          
        &$fp  
        
      

        

    


        
[ Top ]

  

  

	
	
method sync_manifest [line 2263]

	

    

    

		boolean sync_manifest(
)
    

    


	
		Store new Object manifest

Write's an Object's manifest to the remote Object.  This will overwrite  an prior Object manifest.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  $my_docs = $conn->get_container("documents");
    5. 

  5.  $doc = $my_docs->get_object("README");
    6. 

  6.  
    7. 

  7.  # Define new manifest for the object
    8. 

  8.  #
    9. 

  9.  $doc->manifest = "container/prefix";
    10. 

  10.  
    11. 

  11.  # Push the new manifest up to the storage system
    12. 

  12.  #
    13. 

  13.  $doc->sync_manifest();
    14. 






Tags:





  

    return:  True if successful, False otherwise
  

  

    throws:  InvalidResponseException unexpected response
  









	
        
[ Top ]

  

  

	
	
method sync_metadata [line 2221]

	

    

    

		boolean sync_metadata(
)
    

    


	
		Store new Object metadata

Write's an Object's metadata to the remote Object.  This will overwrite  an prior Object metadata.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  $my_docs = $conn->get_container("documents");
    5. 

  5.  $doc = $my_docs->get_object("README");
    6. 

  6.  
    7. 

  7.  # Define new metadata for the object
    8. 

  8.  #
    9. 

  9.  $doc->metadata = array(
    10. 

  10.      "Author" => "EJ",
    11. 

  11.      "Subject" => "How to use the PHP tests",
    12. 

  12.      "Version" => "1.2.2"
    13. 

  13.  );
    14. 

  14.  
    15. 

  15.  # Define additional headers for the object
    16. 

  16.  #
    17. 

  17.  $doc->headers = array(
    18. 

  18.      "Content-Disposition" => "attachment",
    19. 

  19.  );
    20. 

  20.  
    21. 

  21.  # Push the new metadata up to the storage system
    22. 

  22.  #
    23. 

  23.  $doc->sync_metadata();
    24. 






Tags:





  

    return:  True if successful, False otherwise
  

  

    throws:  InvalidResponseException unexpected response
  









	
        
[ Top ]

  

  

	
	
method write [line 2297]

	

    

    

		boolean write(
[string|resource
$data = NULL], [float
$bytes = 0], [boolean
$verify = True])
    

    


	
		Upload Object's data to Cloud Files

Write data to the remote Object.  The $data argument can either be a  PHP resource open for reading (see PHP's fopen() method) or an in-memory  variable.  If passing in a PHP resource, you must also include the $bytes  parameter.
Example:  
  1.  # ... authentication/connection/container code excluded
    2. 

  2.  # ... see previous examples
    3. 

  3.  
    4. 

  4.  $my_docs = $conn->get_container("documents");
    5. 

  5.  $doc = $my_docs->get_object("README");
    6. 

  6.  
    7. 

  7.  # Upload placeholder text in my README
    8. 

  8.  #
    9. 

  9.  $doc->write("This is just placeholder text for now...");
    10. 






Tags:





  

    return:  True when data uploaded successfully
  

  

    throws:  SyntaxException missing required parameters
  

  

    throws:  BadContentTypeException if no Content-Type was/could be set
  

  

    throws:  MisMatchedChecksumException $verify is set and checksums unequal
  

  

    throws:  InvalidResponseException unexpected response
  









	
        
Parameters:

    

    

          

        string|resource  
        $data  
        string or open resource
      

          

        float  
        $bytes  
        amount of data to upload (required for resources)
      

          

        boolean  
        $verify  
        generate, send, and compare MD5 checksums
      

        

    


        
[ Top ]

  

  

	
	
method _guess_content_type [line 1964]

	

    

    

		boolean _guess_content_type(
string
$handle)
    

    


	
		Internal check to get the proper mimetype.

This function would go over the available PHP methods to get  the MIME type.
By default it will try to use the PHP fileinfo library which is  available from PHP 5.3 or as an PECL extension  (http://pecl.php.net/package/Fileinfo).
It will get the magic file by default from the system wide file  which is usually available in /usr/share/magic on Unix or try  to use the file specified in the source directory of the API  (share directory).
if fileinfo is not available it will try to use the internal  mime_content_type function.





Tags:





  

    return:  True if successful
  

  

    throws:  BadContentTypeException
  









	
        
Parameters:

    

    

          

        string  
        $handle  
        name of file or buffer to guess the type from
      

        

    


        
[ Top ]

  

  

	
	
method __toString [line 1937]

	

    

    

		string __toString(
)
    

    


	
		String representation of Object

Pretty print the Object's location and name





Tags:





  

    return:  Object information
  









	
        
[ Top ]

  






        

		    

		    Documentation generated on Wed, 07 Sep 2011 15:19:57 -0500 by phpDocumentor 1.4.3