1 <?php

     2 /**

     3  * Licensed to the Apache Software Foundation (ASF) under one or more

     4  * contributor license agreements. See the NOTICE file distributed with

     5  * this work for additional information regarding copyright ownership.

     6  * The ASF licenses this file to You under the Apache License, Version 2.0

     7  * (the "License"); you may not use this file except in compliance with

     8  * the License. You may obtain a copy of the License at

     9  *

    10  *       http://www.apache.org/licenses/LICENSE-2.0

    11  *

    12  * Unless required by applicable law or agreed to in writing, software

    13  * distributed under the License is distributed on an "AS IS" BASIS,

    14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    15  * See the License for the specific language governing permissions and

    16  * limitations under the License.

    17  *

    18  * @package log4php

    19  */

    20 

    21 /**

    22  * Users should extend this class to implement customized logging

    23  * event filtering. Note that {@link LoggerCategory} and {@link LoggerAppender},

    24  * the parent class of all standard

    25  * appenders, have built-in filtering rules. It is suggested that you

    26  * first use and understand the built-in rules before rushing to write

    27  * your own custom filters.

    28  *

    29  * <p>This abstract class assumes and also imposes that filters be

    30  * organized in a linear chain. The {@link #decide

    31  * decide(LoggerLoggingEvent)} method of each filter is called sequentially,

    32  * in the order of their addition to the chain.

    33  *

    34  * <p>The {@link decide()} method must return one

    35  * of the integer constants {@link LoggerFilter::DENY},

    36  * {@link LoggerFilter::NEUTRAL} or {@link LoggerFilter::ACCEPT}.

    37  *

    38  * <p>If the value {@link LoggerFilter::DENY} is returned, then the log event is

    39  * dropped immediately without consulting with the remaining

    40  * filters.

    41  *

    42  * <p>If the value {@link LoggerFilter::NEUTRAL} is returned, then the next filter

    43  * in the chain is consulted. If there are no more filters in the

    44  * chain, then the log event is logged. Thus, in the presence of no

    45  * filters, the default behaviour is to log all logging events.

    46  *

    47  * <p>If the value {@link LoggerFilter::ACCEPT} is returned, then the log

    48  * event is logged without consulting the remaining filters.

    49  *

    50  * <p>The philosophy of log4php filters is largely inspired from the

    51  * Linux ipchains.

    52  *

    53  * @version $Revision: 1213283 $

    54  * @package log4php

    55  */

    56 abstract class LoggerFilter extends LoggerConfigurable {

    57 

    58     /**

    59      * The log event must be logged immediately without consulting with

    60      * the remaining filters, if any, in the chain.

    61      */

    62     const ACCEPT = 1;

    63 

    64     /**

    65      * This filter is neutral with respect to the log event. The

    66      * remaining filters, if any, should be consulted for a final decision.

    67      */

    68     const NEUTRAL = 0;

    69 

    70     /**

    71      * The log event must be dropped immediately without consulting

    72      * with the remaining filters, if any, in the chain.

    73      */

    74     const DENY = -1;

    75 

    76     /**

    77      * @var LoggerFilter Points to the next {@link LoggerFilter} in the filter chain.

    78      */

    79     protected $next;

    80 

    81     /**

    82      * Usually filters options become active when set. We provide a

    83      * default do-nothing implementation for convenience.

    84      */

    85     public function activateOptions() {

    86     }

    87 

    88     /**

    89      * Decide what to do.

    90      * <p>If the decision is {@link LoggerFilter::DENY}, then the event will be

    91      * dropped. If the decision is {@link LoggerFilter::NEUTRAL}, then the next

    92      * filter, if any, will be invoked. If the decision is {@link LoggerFilter::ACCEPT} then

    93      * the event will be logged without consulting with other filters in

    94      * the chain.

    95      *

    96      * @param LoggerLoggingEvent $event The {@link LoggerLoggingEvent} to decide upon.

    97      * @return integer {@link LoggerFilter::NEUTRAL} or {@link LoggerFilter::DENY}|{@link LoggerFilter::ACCEPT}

    98      */

    99     public function decide(LoggerLoggingEvent $event) {

   100         return self::NEUTRAL;

   101     }

   102 

   103     /**

   104      * Adds a new filter to the filter chain this filter is a part of.

   105      * If this filter has already and follow up filter, the param filter

   106      * is passed on until it is the last filter in chain.

   107      *

   108      * @param $filter - the filter to add to this chain

   109      */

   110     public function addNext($filter) {

   111         if ($this->next !== null) {

   112             $this->next->addNext($filter);

   113         } else {

   114             $this->next = $filter;

   115         }

   116     }

   117 

   118     /**

   119      * Returns the next filter in this chain

   120      * @return the next filter

   121      */

   122     public function getNext() {

   123         return $this->next;

   124     }

   125 

   126 }