[pLog-svn] r1582 - plog/trunk/class/security
oscar at devel.plogworld.net
oscar at devel.plogworld.net
Tue Mar 22 20:34:20 GMT 2005
Author: oscar
Date: 2005-03-22 20:34:20 +0000 (Tue, 22 Mar 2005)
New Revision: 1582
Modified:
plog/trunk/class/security/bayesianfilter.class.php
plog/trunk/class/security/commentfilter.class.php
plog/trunk/class/security/nullpipelinefilter.class.php
plog/trunk/class/security/pipeline.class.php
plog/trunk/class/security/pipelinefilter.class.php
plog/trunk/class/security/pipelinerequest.class.php
plog/trunk/class/security/pipelineresult.class.php
Log:
documentation for the 'security' module
Modified: plog/trunk/class/security/bayesianfilter.class.php
===================================================================
--- plog/trunk/class/security/bayesianfilter.class.php 2005-03-22 20:02:40 UTC (rev 1581)
+++ plog/trunk/class/security/bayesianfilter.class.php 2005-03-22 20:34:20 UTC (rev 1582)
@@ -1,10 +1,5 @@
<?php
- /**
- * @package security
- */
-
-
include_once( PLOG_CLASS_PATH."class/security/pipelinefilter.class.php" );
include_once( PLOG_CLASS_PATH."class/bayesian/bayesiantokenizer.class.php" );
include_once( PLOG_CLASS_PATH."class/dao/bayesiantokens.class.php" );
@@ -26,13 +21,19 @@
define( "BAYESIAN_FILTER_THROW_COMMENT_AWAY_ACTION", 1 );
/**
+ * \ingroup Security
+ *
* Filters the text posted in a comment by a user, to prevent spam-bots. This
* filter only works if the incoming request has the "op" parameter as
* "AddComment", because then it means that we're posting a comment. If it's not
* like that, then we'll quit. Otherwise, the process will continue as normally.
+ *
+ * This filter uses our implementation of the Bayesian filter from the Bayesian module
+ * in order to filter spam comments out. The filter needs some training but after that it should
+ * be fairly reliable.
*/
-
- class BayesianFilter extends PipelineFilter {
+ class BayesianFilter extends PipelineFilter
+ {
function BayesianFilter( $pipelineRequest )
{
@@ -40,7 +41,10 @@
}
/**
- * -- Add function info here --
+ * Processes incoming requests
+ *
+ * @return A positive PipelineResult object is the comment is not spam or a negative
+ * one if it is.
*/
function filter()
{
@@ -112,7 +116,7 @@
}
/**
- * -- Add function info here --
+ * @private
*/
function getSpamProbability($blogId, $topic, $text, $userName, $userEmail, $userUrl)
{
@@ -132,7 +136,7 @@
}
/**
- * -- Add function info here --
+ * @private
*/
function _getMostSignificantTokens($blogId, $tokens)
{
@@ -181,7 +185,7 @@
}
/**
- * -- Add function info here --
+ * @private
*/
function _getBayesProbability($significantTokens)
{
Modified: plog/trunk/class/security/commentfilter.class.php
===================================================================
--- plog/trunk/class/security/commentfilter.class.php 2005-03-22 20:02:40 UTC (rev 1581)
+++ plog/trunk/class/security/commentfilter.class.php 2005-03-22 20:34:20 UTC (rev 1582)
@@ -1,26 +1,38 @@
<?php
- /**
- * @package security
- */
-
-
include_once( PLOG_CLASS_PATH."class/security/pipelinefilter.class.php" );
include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
define( "COMMENT_FILTER_MAXIMUM_SIZE_EXCEEDED", 400 );
/**
+ * \ingroup Security
+ *
* Checks that the post complies with several definable conditions, such as
- * for example its size in bytes and so on.
+ * for example its size in bytes and so on. This filter will only check
+ * incoming requests where there is an "op" parameter with value equal to
+ * "addComment". If so, it will check some extra values to make sure that the comment
+ * is for example not longer than a certain limit (set by the 'maximum_comment_size' config
+ * setting)
+ *
+ *Ê@see PipelineFilter
+ * @see Pipeline
+ * @see PipelineResult
*/
- class CommentFilter extends PipelineFilter {
+ class CommentFilter extends PipelineFilter
+ {
function CommentFilter( $pipelineRequest )
{
$this->PipelineFilter( $pipelineRequest );
}
+ /**
+ * Checks whether incoming comments are not bigger than our configurable threshold, via
+ * the 'maximum_comment_size' config setting
+ *
+ * @return A PipelineResult object
+ */
function filter()
{
// check if we're posting a comment
Modified: plog/trunk/class/security/nullpipelinefilter.class.php
===================================================================
--- plog/trunk/class/security/nullpipelinefilter.class.php 2005-03-22 20:02:40 UTC (rev 1581)
+++ plog/trunk/class/security/nullpipelinefilter.class.php 2005-03-22 20:34:20 UTC (rev 1582)
@@ -1,22 +1,26 @@
<?php
- /**
- * @package security
- */
-
-
include_once( PLOG_CLASS_PATH."class/security/pipelinefilter.class.php" );
/**
+ * \ingroup Security
+ *
* This is the simplest and fastest filter ever: it does nothing :)
+ *
+ * @see Pipeline
+ * @see PipelineFilter
*/
- class NullPipelineFilter extends PipelineFilter {
+ class NullPipelineFilter extends PipelineFilter
+ {
function NullPipelineFilter( $pipelineRequest )
{
$this->PipelineFilter( $pipelineRequest );
}
-
+
+ /**
+ * Always returns a positive result
+ */
function filter()
{
$result = new PipelineResult();
Modified: plog/trunk/class/security/pipeline.class.php
===================================================================
--- plog/trunk/class/security/pipeline.class.php 2005-03-22 20:02:40 UTC (rev 1581)
+++ plog/trunk/class/security/pipeline.class.php 2005-03-22 20:34:20 UTC (rev 1582)
@@ -1,7 +1,11 @@
<?php
/**
- * @package security
+ * \defgroup Security
+ *
+ * The Security module provides a basic implementation of a generic Pipeline to which we can
+ * register "filters", which wil carry out specific actions. Any of the filters can interrupt the
+ * processing, depending on the logic of the filter. Please see the Pipeline class for more information.
*/
@@ -20,11 +24,20 @@
$_pLogPipelineRegisteredFilters;
/**
+ * \ingroup Security
+ *
* Implementation of a basic security framework based on a
* pipeline. Every element of the pipeline implements a simple
* security mechanism. When one of the filters in the pipeline
* find a condition that is matched by the incoming request, the
- * request will be blocked
+ * request will be blocked and the processing of the pipeline will be stopped.
+ *
+ * As of pLog 1.0, plugins can also register new filters dynamically via the PluginBase::registerFilter(), which
+ * eventually uses the static method Pipeline::registerFilter() Since it is static, this method is not restricted
+ * to plugins and can be used by any other class at run time to add new filters.
+ *
+ * The out of the box implementation of the Pipeline comes with a null filter (a filter that does nothing -- go figure :))
+ * and a filter that implements a Bayesian filter for advanced spam protection. See the BayesianFilter class for more information.
*/
class Pipeline extends Object
{
Modified: plog/trunk/class/security/pipelinefilter.class.php
===================================================================
--- plog/trunk/class/security/pipelinefilter.class.php 2005-03-22 20:02:40 UTC (rev 1581)
+++ plog/trunk/class/security/pipelinefilter.class.php 2005-03-22 20:34:20 UTC (rev 1582)
@@ -1,35 +1,60 @@
<?php
- /**
- * @package security
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/security/pipelinerequest.class.php" );
include_once( PLOG_CLASS_PATH."class/security/pipelineresult.class.php" );
/**
+ * \ingroup Security
+ *
* This is the base class from which all the objects that will be used in the
* pipeline will inherit. It defines the basic operations and methods
- * that they'll have to use
+ * that they'll have to use.
+ *
+ * Filters are the basic processing units of the Pipeline. Each filter implements some
+ * logic, according to its purposes and will either accept or reject the incoming request by
+ * returning a positive or negative PipelineResult object from the filter() method. Additionally,
+ * the PipelineResult object allows to specify an error message if needed.
+ *
+ * In case the result is negative, the whole processing of the request by the blog will be stopped
+ * and the user who made the request will be shown the error message via the ErrorView view.
+ *
+ * Please implement at least the filter() method when creating custom filters.
*/
- class PipelineFilter extends Object {
+ class PipelineFilter extends Object
+ {
var $_pipelineRequest;
+ /**
+ * Constructor of the filter.
+ *
+ * @param pipelineRequest a PipelineRequest object that carries information about the
+ * incoming request and so on
+ */
function PipelineFilter( $pipelineRequest )
{
$this->Object();
$this->_pipelineRequest = $pipelineRequest;
}
-
+
+ /**
+ * @return Returns the PipelineRequest object that was passed as a parameter to the constructor
+ */
function getPipelineRequest()
{
return $this->_pipelineRequest;
}
+ /**
+ * This method must be implemented by all child classes extending this one and implements
+ * the actual processing logic of the filter. It always returns a PipelineResult object with
+ * either positive or negative result. Please see the PipelineResult object for more information.
+ *
+ * @return a PipelineResult object
+ * @see Pipelineresult
+ */
function filter()
{
throw( new Exception( "This method must be implemented by child classes!" ));
Modified: plog/trunk/class/security/pipelinerequest.class.php
===================================================================
--- plog/trunk/class/security/pipelinerequest.class.php 2005-03-22 20:02:40 UTC (rev 1581)
+++ plog/trunk/class/security/pipelinerequest.class.php 2005-03-22 20:34:20 UTC (rev 1582)
@@ -1,22 +1,29 @@
<?php
- /**
- * @package security
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
include_once( PLOG_CLASS_PATH."class/dao/bloginfo.class.php" );
/**
+ * \ingroup Security
+ *
* This is the parameter that will be used in the pipeline, to communicate
- * with the filters that 'sit' in the pipeline
+ * with the filters that 'sit' in the pipeline. It carries basic information
+ * such as the incoming HTTP request and a reference to the BlogInfo object
+ * of the blog that is executing the Pipeline.
*/
- class PipelineRequest extends Object {
+ class PipelineRequest extends Object
+ {
var $_httpRequest;
var $_blogInfo;
+ /**
+ * Constructor.
+ *
+ * @param httpRequest An array with the HTTP request
+ * @param blogInfo A BlogInfo object with information about the blog
+ * currently executing the request
+ */
function PipelineRequest( $httpRequest, $blogInfo )
{
$this->Object();
@@ -29,11 +36,18 @@
$this->_blogInfo = $blogInfo;
}
+ /**
+ * @return Returns the BlogInfo object
+ */
function getBlogInfo()
{
return $this->_blogInfo;
}
+ /**
+ * @return Returns a Properties object built from the given HTTP request. Please
+ * use the Properties::getValue() method to retrieve values from the request
+ */
function getHttpRequest()
{
return $this->_httpRequest;
Modified: plog/trunk/class/security/pipelineresult.class.php
===================================================================
--- plog/trunk/class/security/pipelineresult.class.php 2005-03-22 20:02:40 UTC (rev 1581)
+++ plog/trunk/class/security/pipelineresult.class.php 2005-03-22 20:34:20 UTC (rev 1582)
@@ -1,20 +1,29 @@
<?php
- /**
- * @package security
- */
-
-
include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
/**
- * this object is passed from pipeline filters to the pipeline, and
- * carries some information about what the outcome of the processing
- * was
+ * \ingroup Security
+ *
+ * this object is passed from PipelineFilter objects to the Pipeline, and
+ * carries information about what the outcome of the processing
+ * was. If negative (the method PipelineResult::isValid() returns false), then
+ * the processing will be stopped and no more filters will be executed. Control will
+ * be returned to the calling class which will decide what to do.
+ *
+ * @see Pipeline
*/
class PipelineResult extends Object
{
+ /**
+ * Constructor of this type of object
+ *
+ * @param valid By default, all results are positive. If not, please specify otherwise
+ * @param errorCode Which error code to return. Error codes depend on the filter and might
+ * or might not be interpreted by the calling class.
+ * @param errorMessage Error message that should be returned, if any.
+ */
function PipelineResult( $valid = true, $errorCode = 0, $errorMessage = "" )
{
$this->_valid = $valid;
@@ -34,6 +43,8 @@
/**
* Sets whether this is a valid result, or if processing will be stopped here
+ *
+ * @param valid Whether the processing was successful (valid) or not
*/
function setValid( $valid )
{
@@ -55,6 +66,8 @@
/**
* Sets the extended error code.
+ *
+ * @param errorCode the new error code
*/
function setErrorCode( $errorCode )
{
@@ -75,6 +88,8 @@
/**
* Sets the error message.
+ *
+ * @param errorMessage A string representing the new error message
*/
function setErrorMessage( $errorMessage )
{
More information about the pLog-svn
mailing list