      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: }
    127: