File_IMC
[ class tree: File_IMC ] [ index: File_IMC ] [ all elements ]
Packages:
File_IMC
File_Formats


Classes:
File_IMC
File_IMC_Build
File_IMC_Build_Vcard
File_IMC_Exception
File_IMC_Parse
File_IMC_Parse_Vcalendar
File_IMC_Parse_Vcalendar_Event
File_IMC_Parse_Vcalendar_Events
File_IMC_Parse_Vcard
Files:
Build.php
Event.php
Events.php
Exception.php
IMC.php
Parse.php
vcalendar_parse_example.php
Vcard.php
Vcard.php
vcard_build_example.php
vcard_parse_example.php

Class: File_IMC_Build

Source Location: /File_IMC-0.5.0/File/IMC/Build.php

Class Overview




This class helps build files in the vCard and vCalendar formats.




Author(s):






            
                

Version:


    
  
  • Release: 0.5.0
    • 








Variables






Methods















Child classes:






File_IMC_Build_Vcard

	
This class builds a single vCard (version 3.0 or 2.1).









Inherited Variables





Inherited Methods














Class Details



[line 69]

This class helps build files in the vCard and vCalendar formats.
General note: we use the terms "set" "add" and "get" as function  prefixes.
"Set" means there is only one iteration of a property, and it has  only one value repetition, so you set the whole thing at once.
"Add" means either multiple iterations of a property are allowed, or  that there is only one iteration allowed but there can be multiple  value repetitions, so you add iterations or repetitions to the current  stack.
"Get" returns the full vCard line for a single iteration.









[ Top ]







Class Variables



	
	

	
$group = array()

	
[line 90]

  Groups for vCard properties


    

  • Access: public
    • 





  

	

  

    

      Type:  
      array
    

      

	



	
[ Top ]


	
	

	
$lastIter =  null

	
[line 108]

  Tracks which iteration was last used  Used so that iteration need not be specified when adding parameters or groups


    

  • Access: protected
    • 





  

	

  

    

      Type:  
      int
    

      

	



	
[ Top ]


	
	

	
$lastProp =  null

	
[line 99]

  Tracks which property (N, ADR, TEL, etc) value was last set or added.
Used so that property need not be specified when adding parameters or groups


    

  • Access: protected
    • 





  

	

  

    

      Type:  
      string
    

      

	



	
[ Top ]


	
	

	
$param = array()

	
[line 83]

  Parameters for vCard properties


    

  • Access: public
    • 





  

	

  

    

      Type:  
      array
    

      

	



	
[ Top ]


	
	

	
$value = array()

	
[line 76]

  Values for vCard properties


    

  • Access: public
    • 





  

	

  

    

      Type:  
      array
    

      

	



	
[ Top ]










Method Detail



	
	
addParam   [line 304]

	

    

    

		void addParam(
string
$param_name, string
$param_value, [string
$prop = null], [mixed
$iter = null])
    

    


	
		Adds a parameter value for a given property and parameter name.
Note that although vCard 2.1 and vCalendar allow you to specify a  parameter value without a name (e.g., "HOME" instead of  "TYPE=HOME") this class is not so lenient.  ;-)	You must  specify a parameter name (TYPE, ENCODING, etc) when adding a  parameter.  Call multiple times if you want to add multiple values  to the same parameter. E.g.:
$vcard = File_IMC::build('vCard');
// set "TYPE=HOME,PREF" for the first TEL property  $vcard->addParam('TYPE', 'HOME', 'TEL', 0);  $vcard->addParam('TYPE', 'PREF', 'TEL', 0);


    

  • Throws: File_IMC_Excpetion on failure.
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $param_name  
        — 
        The parameter name, such as TYPE, VALUE,  or ENCODING.
      

          

        string  
        $param_value  
        — 
        The parameter value.
      

          

        string  
        $prop  
        — 
        The vCard property for which this is a  paramter (ADR, TEL, etc).  If null, will be the property that was  last set or added-to.
      

          

        mixed  
        $iter  
        — 
        An integer vCard property iteration that this  is a param for.  E.g., if you have more than one ADR property, 0  refers to the first ADR, 1 to the second ADR, and so on.  If null,  the parameter will be added to the last property iteration  available.
      

        

    


        
[ Top ]

  

  
  
	
	
addValue   [line 464]

	

    

    

		void addValue(
string
$prop, int
$iter, int
$part, 
$vals, mixed
$value)
    

    


	
		Generic, all-purpose method to add a repetition of a string or  array in $this->value, in a way suitable for later output as a  vCard element.  This appends the value to be the passed text or  array value, leaving any prior values in place.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $prop  
        — 
        The property to set the value for ('N',  'ADR', etc).
      

          

        int  
        $iter  
        — 
        The property-iteration to set the value for.
      

          

        int  
        $part  
        — 
        The part number of the property-iteration to set  the value for.
      

          

        mixed  
        $value  
        — 
        A string or array; the set of repeated values  for this property-iteration part.
      

          

          
        $vals  
        — 
        
      

        

    


        
[ Top ]

  

  
  
	
	
encode   [line 199]

	

    

    

		void encode(
string
$prop, int
$iter)
    

    


	
		Check if encoding parameter has been set for this property/iteration    If so... it is assumed that the value has already been encoded as such    Otherwide, encode the value if necessary and sets the encoding parameter


    

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $prop  
        — 
        
      

          

        int  
        $iter  
        — 
        
      

        

    


        
[ Top ]

  

  
  
	
	
escape   [line 241]

	

    

    

		void escape(

&$text, mixed
$text)
    

    


	
		Prepares a string so it may be safely used as vCard values.  DO  NOT use this with binary encodings.  Operates on text in-place;  does not return a value.  Recursively descends into arrays.
Escapes a string so that... 	 ; => \; 	 , => \, 	 newline => literal \n


    

  • Throws: File_IMC_Exception on failure.
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        mixed  
        $text  
        — 
        The string or array or strings to escape.
      

          

          
        &$text  
        — 
        
      

        

    


        
[ Top ]

  

  
  
	
	
fetch   [line 144]

	

    

    

		string fetch(
)
    

    


	
		Fetches a full vCard/vCal text block based on $this->value and  $this->param.


    

  • Return: A properly formatted vCard/vCalendar text block.
    • 

  • Abstract: 
    • 







	
Overridden in child classes as:

		

	
File_IMC_Build_Vcard::fetch()

		
Fetches a full vCard text block based on $this->value and

	

	


        
[ Top ]

  

  
  
	
	
getGroup   [line 347]

	

    

    

		string getGroup(
[string
$prop = null], [int
$iter = null])
    

    


	
		Gets back the group for a given property.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $prop  
        — 
        The property to get parameters for (ADR, TEL, etc).
      

          

        int  
        $iter  
        — 
        The vCard property iteration to get the param  list for. E.g., if you have more than one ADR property, 0 refers  to the first ADR, 1 to the second ADR, and so on.
      

        

    


        
[ Top ]

  

  
  
	
	
getMeta   [line 399]

	

    

    

		string getMeta(
string
$prop, [int
$iter = 0])
    

    


	
		Gets the left-side/prefix/before-the-colon (metadata) part of a  vCard line, including the property identifier, the parameter  list, and a colon.


    

  • Return: The line prefix metadata.
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $prop  
        — 
        The property to get metadata for (ADR, TEL, etc).
      

          

        int  
        $iter  
        — 
        The vCard property iteration to get the metadata  for. E.g., if you have more than one ADR property, 0 refers to  the first ADR, 1 to the second ADR, and so on.
      

        

    


        
[ Top ]

  

  
  
	
	
getParam   [line 522]

	

    

    

		string getParam(
string
$prop, [int
$iter = 0])
    

    


	
		Gets back the parameter string for a given property.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $prop  
        — 
        The property to get parameters for (ADR, TEL,  etc).
      

          

        int  
        $iter  
        — 
        The vCard property iteration to get the param  list for. E.g., if you have more than one ADR property, 0 refers  to the first ADR, 1 to the second ADR, and so on.
      

        

    


        
[ Top ]

  

  
  
	
	
getValue   [line 491]

	

    

    

		string getValue(
string
$prop, [int
$iter = 0], [int
$part = 0], [mixed
$rept = null])
    

    


	
		Generic, all-purpose method to get back the data stored in $this->value.


    

  • Return: The value, escaped and delimited, of all  repetitions in the property-iteration part (or specific  repetition within the part).
    • 

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $prop  
        — 
        The property to set the value for ('N','ADR', etc).
      

          

        int  
        $iter  
        — 
        The property-iteration to set the value for.
      

          

        int  
        $part  
        — 
        The part number of the property-iteration to get  the value for.
      

          

        mixed  
        $rept  
        — 
        The repetition number within the part to get;  if null, get all repetitions of the part within the iteration.
      

        

    


        
[ Top ]

  

  
  
	
	
getVersion   [line 185]

	

    

    

		string getVersion(
)
    

    


	
		Gets back the version of the the vCard.  Only one iteration.


    

  • Return: The data-source of the vCard.
    • 

  • Access: public
    • 








        
[ Top ]

  

  
  
	
	
reset   [line 165]

	

    

    

		void reset(
[string
$version = null])
    

    


	
		Resets the vCard values and params to be blank.








        
Parameters:

    

    

          

        string  
        $version  
        — 
        The vCard version to reset to ('2.1' or  '3.0' -- default is the same version as previously set).
      

        

    


        
[ Top ]

  

  
  
	
	
setFromArray   [line 587]

	

    

    

		void setFromArray(
array
$src)
    

    


	
		Builds a vCard/vCal from a parser result array.  Only send  one vCard from the parse-results.
Usage (to build from first vCard in parsed results):
$parse = File_IMC::parse('vCard'); // new parser  $info = $parse->fromFile('sample.vcf'); // parse file
$vcard = File_IMC::build('vCard'); // new builder  $vcard->setFromArray($info);








        
Parameters:

    

    

          

        array  
        $src  
        — 
        One vCard entry as parsed using File_IMC::parse()
      

        

    


        
[ Top ]

  

  
  
	
	
setGroup   [line 374]

	

    

    

		void setGroup(

$groupName, [string
$prop = null], [int
$iter = null], string
$groupNAme)
    

    


	
		Sets the group for a given property.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $groupNAme  
        — 
        The group to assign to the property
      

          

        string  
        $prop  
        — 
        The property (ADR, TEL, etc).   If null, will be the property that was last set or added-to.
      

          

        int  
        $iter  
        — 
        An integer vCard property iteration that this is a param for   If null, will be the iteration that was last set or added-to.
      

          

          
        $groupName  
        — 
        
      

        

    


        
[ Top ]

  

  
  
	
	
setValue   [line 431]

	

    

    

		void setValue(
string
$prop, int
$iter, int
$part, mixed
$value)
    

    


	
		Generic, all-purpose method to store a string or array in  $this->value, in a way suitable for later output as a vCard  element.  This forces the value to be the passed text or array  value, overriding any prior values.


    

  • Access: public
    • 








        
Parameters:

    

    

          

        string  
        $prop  
        — 
        The property to set the value for ('N','ADR', etc).
      

          

        int  
        $iter  
        — 
        The property-iteration to set the value for.
      

          

        int  
        $part  
        — 
        The part number of the property-iteration to set  the value for.
      

          

        mixed  
        $value  
        — 
        A string or array; the set of repeated values  for this property-iteration part.
      

        

    


        
[ Top ]

  

  
  
	
	
setVersion   [line 118]

	

    

    

		mixed setVersion(
[string
$text = '3.0'])
    

    


	
		Sets the version of the specification to use.  Only one iteration.
Overload this function in the driver to validate and set the version


    

  • Return: Void on success, or a PEAR_Error object on failure.
    • 

  • Abstract: 
    • 







	
Overridden in child classes as:

		

	
File_IMC_Build_Vcard::setVersion()

		

	

	


        
Parameters:

    

    

          

        string  
        $text  
        — 
        The text value of the verson text (e.g. '3.0' or '2.1').
      

        

    


        
[ Top ]

  

  
  
	
	
validateParam   [line 136]

	

    

    

		void validateParam(
string
$name, string
$text, [string
$prop = null], [string
$iter = null])
    

    


	
		Validates parameter names and values


    

  • Abstract: 
    • 

  • Throws: File_IMC_Exception if not.
    • 







	
Overridden in child classes as:

		

	
File_IMC_Build_Vcard::validateParam()

		
Validates parameter names and values based on the vCard version  (2.1 or 3.0).

	

	


        
Parameters:

    

    

          

        string  
        $name  
        — 
        The parameter name (e.g., TYPE or ENCODING).
      

          

        string  
        $text  
        — 
        The parameter value (e.g., HOME or BASE64).
      

          

        string  
        $prop  
        — 
        Optional, the property name (e.g., ADR or  PHOTO). Only used for error messaging.
      

          

        string  
        $iter  
        — 
        Optional, the iteration of the property. Only  used for error messaging.
      

        

    


        
[ Top ]

  

  
  
	
	
_setLast   [line 151]

	

    

    

		void _setLast(
string
$prop, in
$iter)
    

    


	
		


    

  • Access: protected
    • 








        
Parameters:

    

    

          

        string  
        $prop  
        — 
        property
      

          

        in  
        $iter  
        — 
        iteration
      

        

    


        
[ Top ]

  

  
  
	
	
__toString   [line 643]

	

    

    

		string __toString(
)
    

    


	
		Magic method to display the vCard/vCal.
  1.  $vcard = File_IMC::build('vCard');
    2. 

  2.  
    3. 

  3.  // set "TYPE=HOME,PREF" for the first TEL property
    4. 

  4.  $vcard->addParam('TYPE', 'HOME', 'TEL', 0);
    5. 

  5.  $vcard->addParam('TYPE', 'PREF', 'TEL', 0);
    6. 

  6.  
    7. 

  7.  echo $vcard;
    8. 



    

  • Access: public
    • 

  • Uses: self::fetch()
    • 








        
[ Top ]

  

  
  



        

		    

		    Documentation generated on Mon, 11 Mar 2019 15:49:38 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright ©  PHP Group 2004.