[pLog-svn] r1642 - in plog/trunk/class/net: . http http/phpsniff
http/session
oscar at devel.plogworld.net
oscar at devel.plogworld.net
Wed Mar 30 14:50:38 GMT 2005
Author: oscar
Date: 2005-03-30 14:50:37 +0000 (Wed, 30 Mar 2005)
New Revision: 1642
Modified:
plog/trunk/class/net/baserequestgenerator.class.php
plog/trunk/class/net/client.class.php
plog/trunk/class/net/customrequestgenerator.class.php
plog/trunk/class/net/customurlhandler.class.php
plog/trunk/class/net/dns.class.php
plog/trunk/class/net/http/httpcache.class.php
plog/trunk/class/net/http/httpclient.class.php
plog/trunk/class/net/http/httpvars.class.php
plog/trunk/class/net/http/phpsniff/phpSniff.class.php
plog/trunk/class/net/http/phpsniff/phpSniff.core.php
plog/trunk/class/net/http/session/sessioninfo.class.php
plog/trunk/class/net/http/session/sessionmanager.class.php
plog/trunk/class/net/http/subdomains.class.php
plog/trunk/class/net/linkformatmatcher.class.php
plog/trunk/class/net/linkparser.class.php
plog/trunk/class/net/modrewriterequestgenerator.class.php
plog/trunk/class/net/prettyrequestgenerator.class.php
plog/trunk/class/net/rawrequestgenerator.class.php
plog/trunk/class/net/request.class.php
plog/trunk/class/net/requestgenerator.class.php
plog/trunk/class/net/url.class.php
plog/trunk/class/net/xmlrpcclient.class.php
Log:
the "net" module... not 100% done but should be good enough
Modified: plog/trunk/class/net/baserequestgenerator.class.php
===================================================================
--- plog/trunk/class/net/baserequestgenerator.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/baserequestgenerator.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,8 +1,13 @@
<?php
- /**
- * @package net
- */
+ /**
+ * \defgroup Net
+ *
+ * The Net package includes all the classes that are related to network functionality in one way
+ * or another.
+ *
+ * @see Net_HTTP
+ */
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
@@ -12,8 +17,22 @@
/**
- * Generates HTTP GET requests in a transparent way:
- * Doing so we can easily change the format of the urls in the future if necessary.
+ * \ingroup Net
+ *
+ * The BaseRequestGenerator class is some sort of proxy class that defines an interface that should be implemented
+ * by classes wishing to provide a new request generator (plus some code that can be reused by all request
+ * generators)
+ *
+ * Each request generator defines its own format for its URLs, and by using request generators we can easily
+ * change the format of our URLs without the need to alter our templates (and therefore, without the need to hardcode
+ * URLs in our templates)
+ *
+ * You should never create instances of BaseRequestGenerator as it defines no code for most of its methods and
+ * will instead throw exceptions. The correct way of getting a request generator is by using the
+ * RequestGenerator factory or whenever we have a BlogInfo object available, by using the
+ * BlogInfo::getBlogRequestGenerator() method.
+ *
+ * @see RequestGenerator
*/
class BaseRequestGenerator extends Object
{
@@ -26,11 +45,18 @@
var $_includeBlogId;
/**
- * Constructor.
+ * Constructor. It initializes certain things such as the base url, checks whether subdomains are
+ * enabled, etc. This method will fetch the values of the following configuration settings:
*
- * @param mode The mode we are going to use.
- * @param xhtml Wether or not requests have to be XHTML compliant. That is, all
- * '&' will be turned into '&'
+ * - base_url: this is the base URL that will be used to generate all other URLs in the system
+ * - subdomains_base_url: if subdomains are enabled, we should also set this URL to something valid. We can
+ * either use {blogname} or {username} to specify whether the URLs should be generated including the
+ * name of the user who owns the blog or the name of the blog.
+ * - include_blog_id_in_url
+ * - script_name: use this setting to rename index.php to something else and still have pLog generate
+ * URLs pointing to the right script.
+ *
+ * @param blogInfo A valid BlogInfo object
*/
function BaseRequestGenerator( $blogInfo = null )
{
@@ -63,16 +89,29 @@
$this->_xhtmlEnabled = true;
}
+ /**
+ * @return Returns true if subdomains are enabled
+ */
function getSubdomainsEnabled()
{
return $this->_subdomainsEnabled;
}
+ /**
+ * @returns true if the blog identifier should be included in the URL. This setting is only meaningful
+ * when subdomains are enabled and is only used by "raw" URLs
+ */
function getIncludeBlogId()
{
return $this->_includeBlogId;
}
+ /**
+ * Returns the base URL that has been configured
+ *
+ * @param useSubdomains If set to true and subdomains are enabled, it will return the base URL as specified
+ * in the subdomains_base_url setting instead of base_url. It defaults to 'true'
+ */
function getBaseUrl( $useSubdomains = true )
{
if( $useSubdomains && $this->_subdomainsEnabled )
@@ -81,11 +120,22 @@
return $this->_baseUrl;
}
+ /**
+ * @return Returns the name of the script to which for example forms will be submitted. Defaults to
+ * index.php but it can be changed via the script_name configuration parameter.
+ */
function getScriptName()
{
return $this->_scriptName;
}
+ /**
+ * @return Returns the URL pointing to the main index file. This URL is built by querying the current
+ * base URL and then appending the value of the script_name configuration setting.
+ *
+ * @param useSubdomains If set to true and subdomains are enabled, it will use the base URL as specified
+ * in the subdomains_base_url setting instead of base_url. It defaults to 'true'.
+ */
function getIndexUrl( $useSubdomains = true )
{
@@ -94,6 +144,13 @@
return $url;
}
+ /**
+ * @return Returns the URL pointing to the admin.php file. This URL is built by querying the current
+ * base URL and then appending the value of the script_name configuration setting.
+ *
+ * @param useSubdomains If set to true and subdomains are enabled, it will use the base URL as specified
+ * in the subdomains_base_url setting instead of base_url. It defaults to 'true'.
+ */
function getAdminUrl( $useSubdomains = true )
{
$url = $this->getBaseUrl( $useSubdomains )."/admin.php";
@@ -101,6 +158,13 @@
return $url;
}
+ /**
+ * @return Returns the URL pointing to the rss.php file. This URL is built by querying the current
+ * base URL and then appending the value of the script_name configuration setting.
+ *
+ * @param useSubdomains If set to true and subdomains are enabled, it will use the base URL as specified
+ * in the subdomains_base_url setting instead of base_url. It defaults to 'true'.
+ */
function getRssUrl( $useSubdomains = false )
{
$url = $this->getBaseUrl( $useSubdomains )."/rss.php";
@@ -108,6 +172,13 @@
return $url;
}
+ /**
+ * @return Returns the URL pointing to the trackback.php file. This URL is built by querying the current
+ * base URL and then appending the value of the script_name configuration setting.
+ *
+ * @param useSubdomains If set to true and subdomains are enabled, it will use the base URL as specified
+ * in the subdomains_base_url setting instead of base_url. It defaults to 'true'.
+ */
function getTrackbackUrl( $useSubdomains = false )
{
$url = $this->getBaseUrl( $useSubdomains )."/trackback.php";
@@ -115,6 +186,13 @@
return $url;
}
+ /**
+ * @return Returns the URL pointing to the resserver.php file. This URL is built by querying the current
+ * base URL and then appending the value of the script_name configuration setting.
+ *
+ * @param useSubdomains If set to true and subdomains are enabled, it will use the base URL as specified
+ * in the subdomains_base_url setting instead of base_url. It defaults to 'true'.
+ */
function getResourceServerUrl( $useSubdomains = false )
{
$url = $this->getBaseUrl( $useSubdomains )."/resserver.php";
@@ -122,6 +200,14 @@
return $url;
}
+ /**
+ * @return Returns the URL pointing to the given parameter. This URL is built by querying the current
+ * base URL and then appending the value of the $res parameter
+ *
+ * @param res A valid URL path
+ * @param useSubdomains If set to true and subdomains are enabled, it will use the base URL as specified
+ * in the subdomains_base_url setting instead of base_url. It defaults to 'true'.
+ */
function getUrl( $res, $useSubdomains = false )
{
$baseUrl = $this->getBaseUrl( $useSubdomains );
@@ -140,13 +226,17 @@
$this->_params[$paramName] = $paramValue;
}
+ /**
+ * @private
+ */
function reset()
{
$this->_params = Array();
}
/**
- * Returns a string representing the request
+ * Returns a string representing the request. Child classes should implement this method in order
+ * to return a meaningful URL.
*
* @return A String object representing the request
*/
@@ -156,7 +246,7 @@
}
/**
- * Returns the permalink for a post
+ * Returns the permalink for a post. Must be implemented by child classes to generate a valid URL.
*
* @param post The Article object
* @return The link for the permalink
@@ -167,7 +257,7 @@
}
/**
- * Returns the comment link for a post
+ * Returns the comment link for a post. Must be implemented by child classes to generate a valid URL.
*
* @param post The Article object
* @return The correct string
@@ -178,7 +268,7 @@
}
/**
- * Returns the link for the post
+ * Returns the link for the post. Must be implemented by child classes to generate a valid URL.
*
* @param post The Article object
* @return The link for the post
@@ -189,8 +279,7 @@
}
/**
- * Returns the link for the post. This is kind of a dirty trick... :( This is only meant to be
- * used in the template that generates the rss feed for a blog.
+ * Returns the link for the post. Must be implemented by child classes to generate a valid URL.
*
* @param post The Article object
* @return The link for the post
@@ -201,22 +290,16 @@
}
/**
- * Returns the url for the link tracker feature
+ * Returns the link of a category. Must be implemented by child classes to generate a valid URL.
+ * This method has been deprecated as of pLog 1.0 so please use the method BaseRequestGenerator::categoryLink()
+ * which takes an ArticleCategory object instead of an Article object since this method does not support
+ * posts that have multiple categories.
*
- * @return The url that shows the results of the link tracker.
- */
- function linkTrackerLink()
- {
- throw( new Exception( "This function must be implemented by child classes." ));
- }
-
- /**
- * Returns the link of a category.
- *
* @param post The post from which we'll fetch the category and then generate the right link.
* @return The url pointing to the page with only the posts belonging to that category.
* @see Article
* @see categoryLink
+ * @deprecated
*/
function postCategoryLink( $post )
{
@@ -224,8 +307,7 @@
}
/**
- * Returns the link but given a category. Does the same as postCategoryLink but this time we don't need
- * a post but an ArticleCategory object.
+ * Returns the link but given a category. Must be implemented by child classes to generate a valid URL.
*
* @see postCategoryLink
* @see ArticleCategory
@@ -239,7 +321,7 @@
}
/**
- * Returns a link to only the articles of the user
+ * Returns a link to only the articles of the user. Must be implemented by child classes to generate a valid URL.
*
* @param user The user whose posts we would like to see
* @param category Optionally, we can specify an ArticleCategory object
@@ -253,7 +335,7 @@
}
/**
- * Returns the url of the host where the blog is running
+ * Returns the url of the host where the blog is running. Must be implemented by child classes to generate a valid URL.
*
* @return Returns the url where the blog is running.
*/
@@ -263,8 +345,9 @@
}
/**
- * Returns the url where the rss feed is running
+ * Returns the url where the rss feed is running. Must be implemented by child classes to generate a valid URL.
*
+ * @param profile The profile whose link we'd like to return (rss090, rss10, rss20 or atom)
* @param blogInfo A BlogInfo object containing information about the blog.
* @return The url pointing to the rss feed of the journal.
* @see BlogInfo
@@ -275,7 +358,7 @@
}
/**
- * Returns the url to reply to a given comment.
+ * Returns the url to reply to a given comment. Must be implemented by child classes to generate a valid URL.
*
* @param post An Article object with information about the post
* @param commen A UserComment object containing information about the post we'd like to reply to.
@@ -289,7 +372,7 @@
}
/**
- * Manually adds the "show more" link in a post.
+ * Manually adds the "show more" link in a post. Must be implemented by child classes to generate a valid URL.
*
* @param post The post we are going to cut.
* @param maxWords Amount of words we'd like to allow.
@@ -302,7 +385,7 @@
}
/**
- * Returns the trackback link for a given post
+ * Returns the trackback link for a given post. Must be implemented by child classes to generate a valid URL.
*
* @param post The post with the necessary information.
* @return A string representing the rdf trackback link.
@@ -312,6 +395,12 @@
throw( new Exception( "This function must be implemented by child classes." ));
}
+ /**
+ * generates an archive link given a date. Must be implemented by child classes to generate a valid URL.
+ *
+ * @param date A Timestamp object
+ * @return A valid archive link
+ */
function getArchiveLink( $date )
{
throw( new Exception( "This function must be implemented by child classes." ));
@@ -319,7 +408,7 @@
/**
- * Returns the link to the page showing the trackback statistics for a given post.
+ * Returns the link to the page showing the trackback statistics for a given post. Must be implemented by child classes to generate a valid URL.
*
* @param post The post with the information.
* @return Returns a string with the valid link.
@@ -331,7 +420,7 @@
/**
* Returns the link to an album. If the parameter is null or zero, then a link to the top level
- * album will be returned.
+ * album will be returned. Must be implemented by child classes to generate a valid URL.
*
* @param album The GalleryAlbum object.
*/
@@ -339,9 +428,32 @@
{
throw( new Exception( "This function must be implemented by child classes." ));
}
+
+ /**
+ * Given an album, generates a link to its parent. Must be implemented by child classes to generate
+ * a valid URL.
+ *
+ * @param album The album
+ */
+ function parentAlbumLink( $album )
+ {
+ throw( new Exception( "This function must be implemented by child classes." ));
+ }
+ <
+ /**
+ * Given the name of a template file, generate the right link to it. Must be implemented by child
+ * classes to generate a valid URL.
+ *
+ * @param template
+ * @return A link to the given template file/static page
+ */
+ function templatePage( $template )
+ {
+ throw( new Exception( "This function must be implemented by child classes." ));
+ }
/**
- * Returns the link to a resource
+ * Returns the link to a resource. Must be implemented by child classes to generate a valid URL.
*
* @param album Generates the correct link to fetch a resource
*/
@@ -351,7 +463,7 @@
}
/**
- * Returns the link to a resource preview
+ * Returns the link to a resource preview. Must be implemented by child classes to generate a valid URL.
*
* @param album Generates the correct link to fetch a resource preview
*/
@@ -359,6 +471,26 @@
{
throw( new Exception( "This function must be implemented by child classes." ));
}
+
+ /**
+ * Returns the link to a resource preview. Must be implemented by child classes to generate a valid URL.
+ *
+ * @param album Generates the correct link to fetch a resource preview
+ */
+ function resourceMediumSizePreviewLink( $resource )
+ {
+ throw( new Exception( "This function must be implemented by child classes." ));
+ }
+
+ /**
+ * Returns the link to a resource. Must be implemented by child classes to generate a valid URL.
+ *
+ * @param resource Generates the correct link to fetch a resource
+ */
+ function resourceDownloadLink( $resource )
+ {
+ throw( new Exception( "This function must be implemented by child classes." ));
+ }
/**
* whether we should generate valid xhtml requests or not
@@ -403,9 +535,12 @@
}
/**
- * get user profile picture link
+ * get user profile picture link. It is not necessary for child classes to implement this method.
+ *
+ * @param blogInfo
*/
- function profileLink($blogInfo = null){
+ function profileLink($blogInfo = null)
+ {
if( $blogInfo == null ) {
$blogInfo = $this->_blogInfo;
}
@@ -418,13 +553,13 @@
} else {
return $this->resourceLink($pic);
}
-
}
/**
* generates the correct path to a file in the template folder, without having to worry
- * whether the template was installed in /templates/ or in /templates/blog_X/
+ * whether the template was installed in /templates/ or in /templates/blog_X/. It is not necessary
+ * for child classes to implement this method.
*
* @param file
* @return A string
@@ -502,4 +637,4 @@
return $url;
}
}
-?>
+?>
\ No newline at end of file
Modified: plog/trunk/class/net/client.class.php
===================================================================
--- plog/trunk/class/net/client.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/client.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,24 +1,21 @@
<?php
- /**
- * @package net
- */
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
- * Very basic functions related to client-side information such as
- * retrieving the "real" ip, user-agent or accepted content type...
+ * \ingroup Net
+ *
+ * Basic class that will return the real IP address of a request. In the future this class
+ * will be improved to return other things such as the user agent, content type, etc.
*/
- class Client extends Object {
+ class Client extends Object
+ {
/**
* Gets the "true" IP address of the current user
*
* @return string the ip of the user
- *
- * @access private
*/
function getIp()
{
Modified: plog/trunk/class/net/customrequestgenerator.class.php
===================================================================
--- plog/trunk/class/net/customrequestgenerator.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/customrequestgenerator.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,24 +1,26 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/net/baserequestgenerator.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
include_once( PLOG_CLASS_PATH."class/data/textfilter.class.php" );
/**
- * Generates URLs using custom formats
+ * \ingroup Net
+ *
+ * Generates requests using a custom format.
+ *
+ * @see RequestGenerator
+ * @see BaseRequestGenerator
*/
class CustomRequestGenerator extends BaseRequestGenerator
{
var $_config;
- /*
+ /**
* Constructor.
+ *
+ * @param blogInfo A BlogInfo object
*/
function CustomRequestGenerator( $blogInfo = null )
{
@@ -43,6 +45,9 @@
return $permaLink;
}
+ /**
+ * @private
+ */
function _fillPostParameters( $post )
{
$t = $post->getDateObject();
@@ -75,6 +80,12 @@
return $params;
}
+ /**
+ * generates an archive link given a date.
+ *
+ * @param date A Timestamp object
+ * @return A valid archive link
+ */
function getArchiveLink( $date )
{
$archiveLinkFormat = $this->_config->getValue( 'archive_link_format' );
@@ -142,17 +153,6 @@
}
/**
- * Returns the url for the link tracker feature
- *
- * @return The url that shows the results of the link tracker.
- */
- function linkTrackerLink()
- {
- $linkTracker = $this->getIndexUrl()."?op=LinkTracker&blogId=".$this->_blogInfo->getId();
- return $linkTracker;
- }
-
- /**
* Returns the link but given a category. Does the same as postCategoryLink but this time we don't need
* a post but an ArticleCategory object.
*
@@ -268,6 +268,12 @@
return $rssLink;
}
+ /**
+ * Returns the trackback link for a given post.
+ *
+ * @param post The post with the necessary information.
+ * @return A string representing the rdf trackback link.
+ */
function postTrackbackLink( $post )
{
$rdfHeader = '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
@@ -344,6 +350,12 @@
return $albumLink;
}
+ /**
+ * Given an album, generates a link to its parent. Must be implemented by child classes to generate
+ * a valid URL.
+ *
+ * @param album The album
+ */
function parentAlbumLink( $album )
{
if( $album->getParentId() == 0 ) {
@@ -361,12 +373,12 @@
return $albumLink;
}
- /**
- * generates a link to an additional template page
- *
- * @param template The name of the template, without the .template extension
- * @return A string with the correct url
- */
+ /**
+ * Given the name of a template file, generate the right link to it.
+ *
+ * @param template
+ * @return A link to the given template file/static page
+ */
function templatePage( $template )
{
$templateLinkFormat = $this->_config->getValue( "template_link_format" );
Modified: plog/trunk/class/net/customurlhandler.class.php
===================================================================
--- plog/trunk/class/net/customurlhandler.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/customurlhandler.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,14 +1,15 @@
<?php
- /**
- * @package net
- */
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
include_once( PLOG_CLASS_PATH."class/net/linkformatmatcher.class.php" );
-
+
+ /**
+ * \ingroup Net
+ *
+ * Parses incoming URLs when "custom URLs" are enabled
+ */
class CustomUrlHandler extends Object
{
Modified: plog/trunk/class/net/dns.class.php
===================================================================
--- plog/trunk/class/net/dns.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/dns.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,20 +1,18 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/misc/osdetect.class.php" );
/**
+ * \ingroup Net
+ *
* Implementation of an alternative version of the checkdnsrr and getmxrr functions which
* are not available in the windows version of the php. The class detects wether we're
* running windows or linux and then depending on the result, we will use the faster and native
* version or the alternative one.
*/
- class Dns extends Object {
+ class Dns extends Object
+ {
/**
* Static function that acts as a wrapper for the native checkdnsrr function. It first detects
Modified: plog/trunk/class/net/http/httpcache.class.php
===================================================================
--- plog/trunk/class/net/http/httpcache.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/http/httpcache.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,67 +1,70 @@
<?php
- /**
- * @package http
- */
-
-
include_once( PLOG_CLASS_PATH."class/net/http/httpvars.class.php" );
-/*
- Enable support for HTTP/1.x conditional requests in PHP.
- Goal: Optimisation
- - If the client sends a HEAD request, avoid transferring data and return the correct headers.
- - If the client already has the same version in its cache, avoid transferring data again (304 Not Modified).
- - Possibility to control cache for client and proxies (public or private policy, life time).
- - When $feedMode is set to true, in the case of a RSS/ATOM feed,
- it puts a timestamp in the global variable $clientCacheDate to allow the sending of only the articles newer than the client's cache.
- - When $compression is set to true, compress the data before sending it to the client and persitent connections are allowed. (Beta1 version)
- Interface:
- - function httpConditional($UnixTimeStamp,$cacheSeconds=0,$cachePrivacy=0,$feedMode=false,$compression=false)
- [Required] $UnixTimeStamp: Date of the last modification of the data to send to the client (Unix Timestamp format).
- [Implied] $cacheSeconds=0: Lifetime in seconds of the document. If $cacheSeconds>0, the document will be cashed and not revalidated against the server for this delay.
- [Implied] $cachePrivacy=0: 0=private, 1=normal (public), 2=forced public. When public, it allows a cashed document ($cacheSeconds>0) to be shared by several users.
- [Implied] $feedMode=false: Special RSS/ATOM feeds. When true, it sets $cachePrivacy to 0 (private), does not use the modification time of the script itself, and puts the date of the client's cache (or a old date from 1980) in the global variable $clientCacheDate.
- [implied] $compression=false: Enable the compression and allows persistant connections.
- Return: True if the connection can be closed (e.g.: the client has already the lastest version), false if the new content has to be send to the client.
- Typical use:
- <?php
- require_once('http-conditional.php');
- //Date of the last modification of the content (Unix Timestamp format).
- //Examples: query the database, or last modification of this script.
- $dateLastModification=...;
- if (httpConditional($dateLastModification))
- {
- ... //Close database connections, and other cleaning.
- exit(); //No need to send anything
- }
- //Do not send any text to the client before this line.
- ... //Rest of the script, just as you would do normally.
- ?>
-
- Version 1.3, 2004-08-05, http://alexandre.alapetite.net/doc-alex/php-http-304/
-
- ------------------------------------------------------------------
- Written by Alexandre Alapetite, http://alexandre.alapetite.net/cv/
-
- Copyright 2004, Licence: Creative Commons "Attribution-ShareAlike 2.0" BY-SA,
- http://creativecommons.org/licenses/by-sa/2.0/
-http://alexandre.alapetite.net/divers/apropos/#by-sa
- - Attribution. You must give the original author credit
- - Share Alike. If you alter, transform, or build upon this work,
- you may distribute the resulting work only under a license identical to this one
- - Any of these conditions can be waived if you get permission from Alexandre Alapetite
- - Please send to Alexandre Alapetite the modifications you make,
- in order to improve this file for the benefit of everybody
-
- If you want to distribute this code, please do it as a link to:
- http://alexandre.alapetite.net/doc-alex/php-http-304/
-*/
-
//In RSS/ATOM feedMode, contains the date of the clients last update.
$clientCacheDate=0; //Global variable because PHP4 does not allow conditional arguments by reference
+/**
+ *
+ * \ingroup Net_HTTP
+ *
+ *
+ * Enable support for HTTP/1.x conditional requests in PHP.
+ * Goal: Optimisation
+ * - If the client sends a HEAD request, avoid transferring data and return the correct headers.
+ * - If the client already has the same version in its cache, avoid transferring data again (304 Not Modified).
+ * - Possibility to control cache for client and proxies (public or private policy, life time).
+ * - When $feedMode is set to true, in the case of a RSS/ATOM feed,
+ * it puts a timestamp in the global variable $clientCacheDate to allow the sending of only the articles newer than the client's cache.
+ * - When $compression is set to true, compress the data before sending it to the client and persitent connections are allowed. (Beta1 version)
+ *
+ *Interface:
+ * - function httpConditional($UnixTimeStamp,$cacheSeconds=0,$cachePrivacy=0,$feedMode=false,$compression=false)
+ * [Required] $UnixTimeStamp: Date of the last modification of the data to send to the client (Unix Timestamp format).
+ * [Implied] $cacheSeconds=0: Lifetime in seconds of the document. If $cacheSeconds>0, the document will be cashed and not revalidated against the server for this delay.
+ * [Implied] $cachePrivacy=0: 0=private, 1=normal (public), 2=forced public. When public, it allows a cashed document ($cacheSeconds>0) to be shared by several users.
+ * [Implied] $feedMode=false: Special RSS/ATOM feeds. When true, it sets $cachePrivacy to 0 (private), does not use the modification time of the script itself, and puts the date of the client's cache (or a old date from 1980) in the global variable $clientCacheDate.
+ * [implied] $compression=false: Enable the compression and allows persistant connections.
+ * Return: True if the connection can be closed (e.g.: the client has already the lastest version), false if the new content has to be send to the client.
+ *
+ * Typical use:
+ *
+ * <pre>
+ * <?php
+ * require_once('http-conditional.php');
+ * //Date of the last modification of the content (Unix Timestamp format).
+ * //Examples: query the database, or last modification of this script.
+ * $dateLastModification=...;
+ * if (httpConditional($dateLastModification))
+ * {
+ * ... //Close database connections, and other cleaning.
+ * exit(); //No need to send anything
+ * }
+ * //Do not send any text to the client before this line.
+ * ... //Rest of the script, just as you would do normally.
+ * ?>
+ * </pre>
+ *
+ * Version 1.3, 2004-08-05, http://alexandre.alapetite.net/doc-alex/php-http-304/
+ *
+ * ------------------------------------------------------------------
+ * Written by Alexandre Alapetite, http://alexandre.alapetite.net/cv/
+ *
+ * Copyright 2004, Licence: Creative Commons "Attribution-ShareAlike 2.0" BY-SA,
+ * http://creativecommons.org/licenses/by-sa/2.0/
+ * http://alexandre.alapetite.net/divers/apropos/#by-sa
+ * - Attribution. You must give the original author credit
+ * - Share Alike. If you alter, transform, or build upon this work,
+ * you may distribute the resulting work only under a license identical to this one
+ * - Any of these conditions can be waived if you get permission from Alexandre Alapetite
+ * - Please send to Alexandre Alapetite the modifications you make,
+ * in order to improve this file for the benefit of everybody
+ *
+ * If you want to distribute this code, please do it as a link to:
+ * http://alexandre.alapetite.net/doc-alex/php-http-304/
+ */
class HttpCache {
function httpConditional($UnixTimeStamp,$cacheSeconds=0,$cachePrivacy=0,$feedMode=false,$compression=false)
{//Credits: http://alexandre.alapetite.net/doc-alex/php-http-304/
Modified: plog/trunk/class/net/http/httpclient.class.php
===================================================================
--- plog/trunk/class/net/http/httpclient.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/http/httpclient.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,16 +1,17 @@
<?php
/**
- * @package http
- */
-
-/*************************************************
-
-Snoopy - the PHP net client
-Author: Monte Ohrt <monte at ispi.net>
-Copyright (c): 1999-2000 ispi, all rights reserved
-Version: 1.0
-
+ *
+ *\ingroup Net_HTTP
+ *
+ * The HttpClient is based on the Snoopy class for making HTTP requests. It is very basic in the
+ * sense that it does not have support for proxies or anything like that, but it works just fine.
+ *
+ * Snoopy - the PHP net client
+ * Author: Monte Ohrt <monte at ispi.net>
+ * Copyright (c): 1999-2000 ispi, all rights reserved
+ * Version: 1.0
+ *
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
@@ -24,21 +25,7 @@
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
-You may contact the author of Snoopy by e-mail at:
-monte at ispi.net
-
-Or, write to:
-Monte Ohrt
-CTO, ispi
-237 S. 70th suite 220
-Lincoln, NE 68510
-
-The latest version of Snoopy can be obtained from:
-http://snoopy.sourceforge.com
-
-*************************************************/
-
+ */
class HttpClient
{
/**** Public variables ****/
Modified: plog/trunk/class/net/http/httpvars.class.php
===================================================================
--- plog/trunk/class/net/http/httpvars.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/http/httpvars.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,13 +1,17 @@
<?php
- /**
- * @package http
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
+
+ /**
+ * \defgroup Net_HTTP
+ *
+ * Package that contains several classes and code related to HTTP, such as code for making
+ * HTTP requests or code for dealing with certain HTTP headers
+ */
/**
+ * \ingroup Net_HTTP
+ *
* HttpVars compatibility package, which allows to fetch some of php's basic
* global variables without having to worry about which version of php we're using.
* The problem here is that since PHP 4.1.0 things like $_REQUEST, $_POST, $_GET, etc
@@ -260,7 +264,6 @@
* @return A string containing the base URL of the script
* @static
*/
-
function getBaseUrl()
{
$serverVars = HttpVars::getServer();
Modified: plog/trunk/class/net/http/phpsniff/phpSniff.class.php
===================================================================
--- plog/trunk/class/net/http/phpsniff/phpSniff.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/http/phpsniff/phpSniff.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -27,6 +27,12 @@
// change these to suit your needs
//===============================================================
+/**
+ * \ingroup Net_HTTP
+ *
+ * The PHPSniff package provides support for detecting the browser capabilities at run-time.
+ *
+ */
class phpSniff extends phpSniff_core
{ var $_version = '2.1.3';
/**
Modified: plog/trunk/class/net/http/phpsniff/phpSniff.core.php
===================================================================
--- plog/trunk/class/net/http/phpsniff/phpSniff.core.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/http/phpsniff/phpSniff.core.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -20,6 +20,12 @@
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*******************************************************************************/
+/**
+ * \ingroup Net_HTTP
+ *
+ * The PHPSniff package provides support for detecting the browser capabilities at run-time.
+ *
+ */
class phpSniff_core
{ // initialize some vars
var $_browser_info = array(
Modified: plog/trunk/class/net/http/session/sessioninfo.class.php
===================================================================
--- plog/trunk/class/net/http/session/sessioninfo.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/http/session/sessioninfo.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,17 +1,16 @@
<?php
- /**
- * @package net
- */
-
include_once( PLOG_CLASS_PATH."class/config/properties.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
/**
+ * \ingroup Net_HTTP
+ *
* Inherits from Properties but just to add some default
* values to some settings
*/
- class SessionInfo extends Properties {
+ class SessionInfo extends Properties
+ {
function SessionInfo()
{
Modified: plog/trunk/class/net/http/session/sessionmanager.class.php
===================================================================
--- plog/trunk/class/net/http/session/sessionmanager.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/http/session/sessionmanager.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -6,21 +6,22 @@
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
/**
- * @package session
+ * \ingroup Net_HTTP
+ *
+ * Class that deals with session, initializing, session cookies, etc. It also takes care of setting
+ * the session folder paths, by calling the method SessionManager::setSessionSavePath().
*/
-
- /**
- * deals with session, initializing, session cookies, etc
- */
class SessionManager extends Object
{
/**
- * static method that takes care of initializing a session if there is none yet
+ * static method that takes care of initializing a session if there is none yet. It will also call
+ * setSessionSavePath() in order to tell PHP where sessions should be read and stored.
*
* @return nothing
* @static
* @see SessionInfo
+ * @see SessionManager::setSessionSavePath()
*/
function init()
{
@@ -86,8 +87,12 @@
}
/**
- * sets the folder where sessions should be saved, in case we'd like to save
- * them somewhere else...
+ * Sets the folder where sessions should be saved, in case we'd like to save
+ * them somewhere else. This class will check the config parameter <b>session_save_path</b>: if
+ * it's not empty, it will use its value as the name of the folder where sessions should be saved, and it
+ * will also take care of creating the folder if it does not exist. If the folder exists but it cannot
+ * be read, it will throw an exception and quit (because this is a big issue)
+ * If the value of this parameter is empty, it will not do anything and use PHP's default settings for this.
*
* @static
*/
Modified: plog/trunk/class/net/http/subdomains.class.php
===================================================================
--- plog/trunk/class/net/http/subdomains.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/http/subdomains.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -6,8 +6,10 @@
include_once( PLOG_CLASS_PATH."class/net/url.class.php" );
/**
+ * \ingroup Net_HTTP
+ *
* encapsulates most of the logic needed to extract info about
- * the subdomain given a subdomain url
+ * the subdomain, given a subdomain url
*/
class Subdomains extends Object
{
Modified: plog/trunk/class/net/linkformatmatcher.class.php
===================================================================
--- plog/trunk/class/net/linkformatmatcher.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/linkformatmatcher.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,14 +1,11 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/net/linkparser.class.php" );
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
+ * \ingroup Net
+ *
* identifies the right kind of url, based on the format of our links
*/
class LinkFormatMatcher extends Object
Modified: plog/trunk/class/net/linkparser.class.php
===================================================================
--- plog/trunk/class/net/linkparser.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/linkparser.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,10 +1,6 @@
<?php
- /**
- * @package net
- */
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
//
@@ -34,6 +30,9 @@
'{albumname}' => '([_0-9a-zA-Z- ]+)?'
);
+ /**
+ * \ingroup Net
+ */
class LinkParser extends Object
{
Modified: plog/trunk/class/net/modrewriterequestgenerator.class.php
===================================================================
--- plog/trunk/class/net/modrewriterequestgenerator.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/modrewriterequestgenerator.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,22 +1,23 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/net/baserequestgenerator.class.php" );
include_once( PLOG_CLASS_PATH."class/data/stringutils.class.php" );
/**
+ * \ingroup Net
+ *
* Generates search-engine friendly URLs and uses Apache mod_rewrite to parse them
*
+ * @see RequestGenerator
+ * @see BaseRequestGenerator
*/
class ModRewriteRequestGenerator extends BaseRequestGenerator
{
- /**
+ /**
* Constructor.
+ *
+ * @param blogInfo A BlogInfo object
*/
function ModRewriteRequestGenerator( $blogInfo )
{
@@ -89,23 +90,6 @@
}
/**
- * Returns the url for the link tracker feature
- *
- * @return The url that shows the results of the link tracker.
- */
- function linkTrackerLink()
- {
- $this->addParameter( "op", "LinkTracker" );
- if( $this->_blogInfo != null )
- $this->addParameter( "blogId", $this->_blogInfo->getId());
-
- //$linkTracker = $_SERVER["PHP_SELF"].$rg->getRequest();
- $linkTracker = $this->getIndexUrl().$this->getRequest();
-
- return $linkTracker;
- }
-
- /**
* Returns the link of a category.
*
* @param post The post from which we'll fetch the category and then generate the right link.
@@ -226,7 +210,12 @@
return $link;
}
-
+ /**
+ * Returns the trackback link for a given post.
+ *
+ * @param post The post with the necessary information.
+ * @return A string representing the rdf trackback link.
+ */
function postTrackbackLink( $post )
{
$rdfHeader = '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
@@ -268,6 +257,12 @@
return $replyCommentLink;
}
+ /**
+ * generates an archive link given a date.
+ *
+ * @param date A Timestamp object
+ * @return A valid archive link
+ */
function getArchiveLink( $date )
{
@@ -312,6 +307,12 @@
return $link;
}
+ /**
+ * Given an album, generates a link to its parent. Must be implemented by child classes to generate
+ * a valid URL.
+ *
+ * @param album The album
+ */
function parentAlbumLink( $album )
{
if( $album->getParentId() > 0 )
@@ -329,6 +330,12 @@
return $albumLink;
}
+ /**
+ * Given the name of a template file, generate the right link to it.
+ *
+ * @param template
+ * @return A link to the given template file/static page
+ */
function templatePage( $template )
{
$templatePage = $this->getBaseUrl().'/'.$this->_blogInfo->getId().'_'.StringUtils::text2url( $this->_blogInfo->getBlog() ).'/'.$template;
Modified: plog/trunk/class/net/prettyrequestgenerator.class.php
===================================================================
--- plog/trunk/class/net/prettyrequestgenerator.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/prettyrequestgenerator.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -8,12 +8,20 @@
include_once( PLOG_CLASS_PATH."class/net/baserequestgenerator.class.php" );
/**
- * Generates 'pretty' URLs
+ * \ingroup Net
+ *
+ * Generates prettier but non-customizable requests.
+ *
+ * @see RequestGenerator
+ * @see BaseRequestGenerator
*/
- class PrettyRequestGenerator extends BaseRequestGenerator {
+ class PrettyRequestGenerator extends BaseRequestGenerator
+ {
- /*
+ /**
* Constructor.
+ *
+ * @param blogInfo A BlogInfo object
*/
function PrettyRequestGenerator( $blogInfo )
{
@@ -34,6 +42,12 @@
return $permaLink;
}
+ /**
+ * generates an archive link given a date.
+ *
+ * @param date A Timestamp object
+ * @return A valid archive link
+ */
function getArchiveLink( $date )
{
$archiveLink = $this->getBaseUrl()."/archives";
@@ -86,19 +100,6 @@
}
/**
- * Returns the url for the link tracker feature
- *
- * @return The url that shows the results of the link tracker.
- */
- function linkTrackerLink()
- {
-
- $linkTracker = $this->getBaseUrl()."/linktracker/".$this->_blogInfo->getId();
-
- return $linkTracker;
- }
-
- /**
* Returns the link of a category.
*
* @param post The post from which we'll fetch the category and then generate the right link.
@@ -227,6 +228,12 @@
return $rssLink;
}
+ /**
+ * Returns the trackback link for a given post.
+ *
+ * @param post The post with the necessary information.
+ * @return A string representing the rdf trackback link.
+ */
function postTrackbackLink( $post )
{
$rdfHeader = '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
@@ -288,6 +295,12 @@
return $albumLink;
}
+ /**
+ * Given an album, generates a link to its parent. Must be implemented by child classes to generate
+ * a valid URL.
+ *
+ * @param album The album
+ */
function parentAlbumLink( $album )
{
$albumLink = $this->getBaseUrl()."/album/".$this->_blogInfo->getId()."/".$album->getParentId();
@@ -295,6 +308,13 @@
return $albumLink;
}
+ /**
+ * Given the name of a template file, generate the right link to it. Must be implemented by child
+ * classes to generate a valid URL.
+ *
+ * @param template
+ * @return A link to the given template file/static page
+ */
function templatePage( $template )
{
$templatePage = $this->getBaseUrl()."/static/".$this->_blogInfo->getId()."/".$template;
Modified: plog/trunk/class/net/rawrequestgenerator.class.php
===================================================================
--- plog/trunk/class/net/rawrequestgenerator.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/rawrequestgenerator.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,27 +1,22 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/net/baserequestgenerator.class.php" );
/**
- * Generates HTTP GET requests in a transparent way:
+ * \ingroup Net
*
- * <i>
- * $g = new RequestGenerator()<br>
- * $g->addParameter( "op", "ViewArticle" );<br>
- * $g->addParameter( "articleId", 1 );<br>
- * $request = $g->getRequest();<br>
- * </i><br>
- * Doing so we can easily change the format of the urls in the future if necessary.
+ * Generates normal, plain HTTP requests.
+ *
+ * @see RequestGenerator
+ * @see BaseRequestGenerator
*/
- class RawRequestGenerator extends BaseRequestGenerator {
+ class RawRequestGenerator extends BaseRequestGenerator
+ {
- /**
+ /**
* Constructor.
+ *
+ * @param blogInfo A BlogInfo object
*/
function RawRequestGenerator( $blogInfo )
{
@@ -33,12 +28,16 @@
*
* @param paramName Name of the parameter
* @param paramValue Value given to the parameter
+ * @private
*/
function addParameter( $paramName, $paramValue )
{
$this->_params[$paramName] = $paramValue;
}
+ /**
+ * @private
+ */
function removeParameter( $paramName )
{
unset( $this->_params[$paramName] );
@@ -114,23 +113,6 @@
}
/**
- * Returns the url for the link tracker feature
- *
- * @return The url that shows the results of the link tracker.
- */
- function linkTrackerLink()
- {
- $this->addParameter( "op", "LinkTracker" );
- if( $this->_blogInfo != null )
- $this->addParameter( "blogId", $this->_blogInfo->getId());
-
- //$linkTracker = $_SERVER["PHP_SELF"].$rg->getRequest();
- $linkTracker = $this->getIndexUrl().$this->getRequest();
-
- return $linkTracker;
- }
-
- /**
* Returns the link of a category.
*
* @param post The post from which we'll fetch the category and then generate the right link.
@@ -266,6 +248,12 @@
return $rssLink;
}
+ /**
+ * Returns the trackback link for a given post.
+ *
+ * @param post The post with the necessary information.
+ * @return A string representing the rdf trackback link.
+ */
function postTrackbackLink( $post )
{
$rdfHeader = '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
@@ -306,6 +294,12 @@
return $replyCommentLink;
}
+ /**
+ * generates an archive link given a date.
+ *
+ * @param date A Timestamp object
+ * @return A valid archive link
+ */
function getArchiveLink( $date )
{
$this->addParameter( "op", "Default" );
@@ -355,6 +349,12 @@
return $albumLink;
}
+ /**
+ * Given an album, generates a link to its parent. Must be implemented by child classes to generate
+ * a valid URL.
+ *
+ * @param album The album
+ */
function parentAlbumLink( $album )
{
$this->addParameter( "op", "ViewAlbum" );
@@ -366,6 +366,12 @@
return $albumLink;
}
+ /**
+ * Given the name of a template file, generate the right link to it.
+ *
+ * @param template
+ * @return A link to the given template file/static page
+ */
function templatePage( $template )
{
$this->addParameter( "op", "Template" );
Modified: plog/trunk/class/net/request.class.php
===================================================================
--- plog/trunk/class/net/request.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/request.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/config/properties.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
@@ -14,6 +9,8 @@
define( "SEARCH_ENGINE_FRIENDLY_MODE", 2);
/**
+ * \ingroup Net
+ *
* Represents a request in our system. Doing so we can in the future
* change the format requests are recognized since all the dirty
* stuff would be done here. After that, using an interface of the type
@@ -26,6 +23,11 @@
var $_paramsRaw;
+ /**
+ * Initializes the request object
+ *
+ * @param values An associative array that will be used to initialize the object
+ */
function Request( $values = null )
{
if( $values == null )
Modified: plog/trunk/class/net/requestgenerator.class.php
===================================================================
--- plog/trunk/class/net/requestgenerator.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/requestgenerator.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
if ( !defined("CHECK_CONFIG_REQUEST_MODE") )
@@ -18,6 +13,51 @@
if ( !defined("CUSTOM_REQUEST_MODE") )
define( "CUSTOM_REQUEST_MODE", 4 );
+ /**
+ * \ingroup Net
+ *
+ * Request generators are a way to allow the templates to generate links in an abstract manner regarding of the
+ * current settings. Each request generator defines its own format for its URLs, and by using request generators
+ * we can easily change the format of our URLs without the need to alter our templates
+ * (and therefore, without the need to hardcode URLs in our templates)
+ *
+ * This is the class that implements the factory pattern to obtain the correct request generator, given
+ * a BlogInfo object and optionally, a request generator type. If not type is given, then
+ * the class will check the value of the <b>request_format_mode</b> configuration parameter.
+ *
+ * The four types of request generators supported as of pLog 1.0 are:
+ *
+ * - NORMAL_REQUEST_MODE
+ * - SEARCH_ENGINE_FRIENDLY_MODE
+ * - MODREWRITE_MODE
+ * - CUSTOM_REQUEST_MODE
+ *
+ * The preferred way to obtain a request generator is:
+ *
+ * <pre>
+ * $rg =& RequestGenerator::getRequestGenerator( $blogInfo );
+ * ...
+ * $blogLink = $rg->blogLink();
+ * </pre>
+ *
+ * In order to force the factory class to generate a specific request generator:
+ *
+ * <pre>
+ * $rg =& RequestGenerator::getRequestGenerator( $blogInfo, CUSTOM_REQUEST_MODE );
+ * </pre>
+ *
+ * However, in cases when we have a BlogInfo available it is even better to use the BlogInfo::getBlogRequestGenerator()
+ * method:
+ *
+ * <pre>
+ * $rg = $blogInfo->getBlogRequestGenerator();
+ * ...
+ * $blogLink = $rg->blogLink();
+ * </pre>
+ *
+ * In order to check which methods are available to request generators, please see the documentation of the
+ * RequestGenerator proxy class.
+ */
class RequestGenerator extends Object
{
Modified: plog/trunk/class/net/url.class.php
===================================================================
--- plog/trunk/class/net/url.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/url.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,26 +1,22 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
+ * \ingroup Net
+ *
* Encapsulates a definition of an object representing a URL
*
* Provides getters and setters for all the parts of the url:
* <ul>
* <li>url (the complete url)</li>
- * <li>scheme</li>
+ * <li>scheme (http, file, ftp)</li>
* <li>host</li>
* <li>user</li>
* <li>password</li>
* <li>path</li>
- * <li>query</li>
- * <li>fragment</li>
- *
+ * <li>query (anything after the question mark "?")</li>
+ * <li>fragment (anything after the hash mark "#")</li>
* </ul>
* Every time a change is made in one of the fields the
* url string is recalculated so that any call to getUrl
@@ -39,6 +35,13 @@
var $_query;
var $_fragment;
+ /**
+ * given a string representing a valid URL, build the object. If the string is not a valid
+ * URL, the constructor will not generate an error but the results of calling any of the getter
+ * methods are undefined
+ *
+ * @param url A string with a valid URL
+ */
function Url( $url )
{
$this->Object();
@@ -48,6 +51,9 @@
$this->_calculateFields();
}
+ /**
+ * @private
+ */
function _calculateFields()
{
$parts = parse_url( $this->_url );
@@ -64,11 +70,19 @@
}
}
+ /**
+ * @return returns the URL as it was given in the constructor
+ */
function getUrl()
{
return $this->_url;
}
+ /**
+ * sets a new URL string, which will overwrite the previous one.
+ *
+ * @param the new URL string
+ */
function setUrl( $url )
{
$this->_url = $url;
@@ -76,11 +90,19 @@
$this->_calculateFields();
}
+ /**
+ * @return returns the scheme of the given url (http, file, ftp, ...)
+ */
function getScheme()
{
return $this->_scheme;
}
+ /**
+ * sets a new scheme
+ *
+ * @param Scheme The new scheme (http, file, ftp, ...)
+ */
function setScheme( $scheme )
{
$this->_scheme = $scheme;
@@ -88,11 +110,19 @@
$this->glueUrl();
}
+ /**
+ * @return Returns the host specified in this URL
+ */
function getHost()
{
return $this->_host;
}
+ /**
+ * sets a new host
+ *
+ * @param Host the new host
+ */
function setHost( $host )
{
$this->_host = $host;
@@ -100,11 +130,20 @@
$this->glueUrl();
}
+ /**
+ * @return Returns the port that was specified in the original URL, or 80 if there was nothing
+ * specified
+ */
function getPort()
{
return $this->_port;
}
+ /**
+ * sets a new port
+ *
+ * @param port the new port
+ */
function setPort( $port )
{
$this->_port = $port;
@@ -112,11 +151,19 @@
$this->glueUrl();
}
+ /**
+ * @return Returns the user that was specified in the URL, if any.
+ */
function getUser()
{
return $this->_user;
}
+ /**
+ * sets a new user in the URL
+ *
+ * @param user The new username
+ */
function setUser( $user )
{
$this->_user = $user;
@@ -124,11 +171,19 @@
$this->glueUrl();
}
+ /**
+ * @return Returns the password that was set in the URL
+ */
function getPass()
{
return $this->_pass;
}
+ /**
+ * sets a new password in the URL
+ *
+ * @param pass the new password
+ */
function setPass( $pass )
{
$this->_pass = $pass;
@@ -136,11 +191,19 @@
$this->glueUrl();
}
+ /**
+ * @return Returns the path
+ */
function getPath()
{
return $this->_path;
}
+ /**
+ * sets the new path
+ *
+ * @param path The new path
+ */
function setPath( $path )
{
$this->_path = $path;
@@ -148,6 +211,9 @@
$this->glueUrl();
}
+ /**
+ * @return Returns the query
+ */
function getQuery()
{
return $this->_query;
@@ -178,6 +244,11 @@
return $results;
}
+ /**
+ * sets a new query
+ *
+ * @param query The new query
+ */
function setQuery( $query )
{
$this->_query = $query;
@@ -185,11 +256,19 @@
$this->glueUrl();
}
+ /**
+ * @return Returns the fragment
+ */
function getFragment()
{
return $this->_fragment;
}
+ /**
+ * Sets a new fragment
+ *
+ * @param fragment The new fragment
+ */
function setFragment( $fragment )
{
$this->_fragment = $fragment;
@@ -199,12 +278,19 @@
/**
* Puts all the pieces back in place, and returns the resulting
- * url.
+ * url. It is usually not necessary to call this method to obtain the new URL once we've called
+ * any of the setter methods of this class, since it is done automatically. Doing
*
- * This function is useful if we changed any of the parts individually and
- * want to get the resulting url
+ * <pre>
+ * $url->setScheme( "ftp" );
+ * print("new url = ".$url->getUrl());
+ * </pre>
*
+ * is enough to obtain the updated URL string.
+ *
* Extracted from http://www.php.net/manual/en/function.parse-url.php
+ *
+ * @return a valid URL generated from the different parts of the object
*/
function glueUrl()
{
Modified: plog/trunk/class/net/xmlrpcclient.class.php
===================================================================
--- plog/trunk/class/net/xmlrpcclient.class.php 2005-03-30 12:20:01 UTC (rev 1641)
+++ plog/trunk/class/net/xmlrpcclient.class.php 2005-03-30 14:50:37 UTC (rev 1642)
@@ -1,16 +1,13 @@
<?php
- /**
- * @package net
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/net/xmlrpc/IXR_Library.lib.php" );
- /**
- * Implements a very basic XMLRPC client, which offers methods such as
- * ping, implementing the weblogUpdates.ping methods.
+ /**
+ * \ingroup Net
+ *
+ * Implements a basic XMLRPC client, which offers methods such as
+ * ping (implementing the weblogUpdates.ping methods)
*/
class XmlRpcClient extends IXR_Client
{
More information about the pLog-svn
mailing list