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: