CodeIgniter4/incoming/filters.html
2019-02-18 11:53:51 -08:00

467 lines
23 KiB
HTML

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Controller Filters &mdash; CodeIgniter4 4.0.0-alpha.5 documentation</title>
<link rel="shortcut icon" href="../_static/ci-icon.ico"/>
<link rel="stylesheet" href="../_static/css/citheme.css" type="text/css" />
<link rel="top" title="CodeIgniter4 4.0.0-alpha.5 documentation" href="../index.html"/>
<link rel="up" title="Controllers and Routing" href="index.html"/>
<link rel="next" title="HTTP Messages" href="message.html"/>
<link rel="prev" title="URI Routing" href="routing.html"/>
<script src="../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="../index.html" class="icon icon-home"> CodeIgniter4
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../intro/index.html">Welcome to CodeIgniter4</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../installation/index.html">Installation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../concepts/index.html">CodeIgniter4 Overview</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../general/index.html">General Topics</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Controllers and Routing</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="controllers.html">Controllers</a></li>
<li class="toctree-l2"><a class="reference internal" href="routing.html">URI Routing</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Controller Filters</a></li>
<li class="toctree-l2"><a class="reference internal" href="message.html">HTTP Messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="request.html">Request Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="incomingrequest.html">IncomingRequest Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="content_negotiation.html">Content Negotiation</a></li>
<li class="toctree-l2"><a class="reference internal" href="methodspoofing.html">HTTP Method Spoofing</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../outgoing/index.html">Building Responses</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../database/index.html">Working With Databases</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../models/index.html">Modeling Data</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../dbmgmt/index.html">Managing Databases</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Library Reference</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../helpers/index.html">Helpers</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../testing/index.html">Testing</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../cli/index.html">Command Line Usage</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../extending/index.html">Extending CodeIgniter</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../license.html">The MIT License (MIT)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../changelogs/index.html">Change Logs</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">CodeIgniter4</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> &raquo;</li>
<li><a href="index.html">Controllers and Routing</a> &raquo;</li>
<li>Controller Filters</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="controller-filters">
<h1>Controller Filters<a class="headerlink" href="#controller-filters" title="Permalink to this headline"></a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#creating-a-filter" id="id1">Creating a Filter</a><ul>
<li><a class="reference internal" href="#before-filters" id="id2">Before Filters</a></li>
<li><a class="reference internal" href="#after-filters" id="id3">After Filters</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-filters" id="id4">Configuring Filters</a><ul>
<li><a class="reference internal" href="#aliases" id="id5">$aliases</a></li>
<li><a class="reference internal" href="#globals" id="id6">$globals</a></li>
<li><a class="reference internal" href="#methods" id="id7">$methods</a></li>
<li><a class="reference internal" href="#filters" id="id8">$filters</a></li>
</ul>
</li>
<li><a class="reference internal" href="#provided-filters" id="id9">Provided Filters</a></li>
</ul>
</div>
<p>Controller Filters allow you to perform actions either before or after the controllers execute. Unlike <a class="reference internal" href="../extending/events.html"><span class="doc">events</span></a>,
you can very simply choose which URI&#8217;s in your application have the filters applied to them. Incoming filters may
modify the Request, while after filters can act on and even modify the Response, allowing for a lot of flexibility
and power. Some common examples of tasks that might be performed with filters are:</p>
<ul class="simple">
<li>Performing CSRF protection on the incoming requests</li>
<li>Restricting areas of your site based upon their Role</li>
<li>Perform rate limiting on certain endpoints</li>
<li>Display a &#8220;Down for Maintenance&#8221; page</li>
<li>Perform automatic content negotiation</li>
<li>and more..</li>
</ul>
<div class="section" id="creating-a-filter">
<h2><a class="toc-backref" href="#id1">Creating a Filter</a><a class="headerlink" href="#creating-a-filter" title="Permalink to this headline"></a></h2>
<p>Filters are simple classes that implement <code class="docutils literal"><span class="pre">CodeIgniter\Filters\FilterInterface</span></code>.
They contain two methods: <code class="docutils literal"><span class="pre">before()</span></code> and <code class="docutils literal"><span class="pre">after()</span></code> which hold the code that
will run before and after the controller respectively. Your class must contain both methods
but may leave the methods empty if they are not needed. A skeleton filter class looks like:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="o">&lt;?</span><span class="nx">php</span> <span class="k">namespace</span> <span class="nx">App\Filters</span><span class="p">;</span>
<span class="k">use</span> <span class="nx">CodeIgniter\HTTP\RequestInterface</span><span class="p">;</span>
<span class="k">use</span> <span class="nx">CodeIgniter\HTTP\ResponseInterface</span><span class="p">;</span>
<span class="k">use</span> <span class="nx">CodeIgniter\Filters\FilterInterface</span><span class="p">;</span>
<span class="k">class</span> <span class="nc">MyFilter</span> <span class="k">implements</span> <span class="nx">FilterInterface</span>
<span class="p">{</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">before</span><span class="p">(</span><span class="nx">RequestInterface</span> <span class="nv">$request</span><span class="p">)</span>
<span class="p">{</span>
<span class="c1">// Do something here</span>
<span class="p">}</span>
<span class="c1">//--------------------------------------------------------------------</span>
<span class="k">public</span> <span class="k">function</span> <span class="nf">after</span><span class="p">(</span><span class="nx">RequestInterface</span> <span class="nv">$request</span><span class="p">,</span> <span class="nx">ResponseInterface</span> <span class="nv">$response</span><span class="p">)</span>
<span class="p">{</span>
<span class="c1">// Do something here</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="section" id="before-filters">
<h3><a class="toc-backref" href="#id2">Before Filters</a><a class="headerlink" href="#before-filters" title="Permalink to this headline"></a></h3>
<p>From any filter, you can return the <code class="docutils literal"><span class="pre">$request</span></code> object and it will replace the current Request, allowing you
to make changes that will still be present when the controller executes.</p>
<p>Since before filters are executed prior to your controller being executed, you may at times want to stop the
actions in the controller from happening. You can do this by passing back anything that is not the request object.
This is typically used to peform redirects, like in this example:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="k">public</span> <span class="k">function</span> <span class="nf">before</span><span class="p">(</span><span class="nx">RequestInterface</span> <span class="nv">$request</span><span class="p">)</span>
<span class="p">{</span>
<span class="nv">$auth</span> <span class="o">=</span> <span class="nx">service</span><span class="p">(</span><span class="s1">&#39;auth&#39;</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span> <span class="nv">$auth</span><span class="o">-&gt;</span><span class="na">isLoggedIn</span><span class="p">())</span>
<span class="p">{</span>
<span class="k">return</span> <span class="nx">redirect</span><span class="p">(</span><span class="s1">&#39;login&#39;</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If a Response instance is returned, the Response will be sent back to the client and script execution will stop.
This can be useful for implementing rate limiting for API&#8217;s. See <strong>app/Filters/Throttle.php</strong> for an
example.</p>
</div>
<div class="section" id="after-filters">
<h3><a class="toc-backref" href="#id3">After Filters</a><a class="headerlink" href="#after-filters" title="Permalink to this headline"></a></h3>
<p>After filters are nearly identical to before filters, except that you can only return the <code class="docutils literal"><span class="pre">$response</span></code> object,
and you cannot stop script execution. This does allow you to modify the final output, or simply do something with
the final output. This could be used to ensure certain security headers were set the correct way, or to cache
the final output, or even to filter the final output with a bad words filter.</p>
</div>
</div>
<div class="section" id="configuring-filters">
<h2><a class="toc-backref" href="#id4">Configuring Filters</a><a class="headerlink" href="#configuring-filters" title="Permalink to this headline"></a></h2>
<p>Once you&#8217;ve created your filters, you need to configure when they get run. This is done in <code class="docutils literal"><span class="pre">app/Config/Filters.php</span></code>.
This file contains four properties that allow you to configure exactly when the filters run.</p>
<div class="section" id="aliases">
<h3><a class="toc-backref" href="#id5">$aliases</a><a class="headerlink" href="#aliases" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal"><span class="pre">$aliases</span></code> array is used to associate a simple name with one or more fully-qualified class names that are the
filters to run:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="k">public</span> <span class="nv">$aliases</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;csrf&#39;</span> <span class="o">=&gt;</span> <span class="nx">\CodeIgniter\Filters\CSRF</span><span class="o">::</span><span class="na">class</span>
<span class="p">];</span>
</pre></div>
</div>
<p>Aliases are mandatory and if you try to use a full class name later, the system will throw an error. Defining them
in this way makes it simple to switch out the class used. Great for when you decided you need to change to a
different authentication system since you only change the filter&#8217;s class and you&#8217;re done.</p>
<p>You can combine multiple filters into one alias, making complex sets of filters simple to apply:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="k">public</span> <span class="nv">$aliases</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;apiPrep&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span>
<span class="nx">\App\Filters\Negotiate</span><span class="o">::</span><span class="na">class</span><span class="p">,</span>
<span class="nx">\App\Filters\ApiAuth</span><span class="o">::</span><span class="na">class</span>
<span class="p">]</span>
<span class="p">];</span>
</pre></div>
</div>
<p>You should define as many aliases as you need.</p>
</div>
<div class="section" id="globals">
<h3><a class="toc-backref" href="#id6">$globals</a><a class="headerlink" href="#globals" title="Permalink to this headline"></a></h3>
<p>The second section allows you to define any filters that should be applied to every request made by the framework.
You should take care with how many you use here, since it could have performance implications to have too many
run on every request. Filters can be specified by adding their alias to either the before or after array:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="k">public</span> <span class="nv">$globals</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;before&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span>
<span class="s1">&#39;csrf&#39;</span>
<span class="p">],</span>
<span class="s1">&#39;after&#39;</span> <span class="o">=&gt;</span> <span class="p">[]</span>
<span class="p">];</span>
</pre></div>
</div>
<p>There are times where you want to apply a filter to almost every request, but have a few that should be left alone.
One common example is if you need to exclude a few URI&#8217;s from the CSRF protection filter to allow requests from
third-party websites to hit one or two specific URI&#8217;s, while keeping the rest of them protected. To do this, add
an array with the &#8216;except&#8217; key and a uri to match as the value alongside the alias:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="k">public</span> <span class="nv">$globals</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;before&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span>
<span class="s1">&#39;csrf&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;except&#39;</span> <span class="o">=&gt;</span> <span class="s1">&#39;api/*&#39;</span><span class="p">]</span>
<span class="p">],</span>
<span class="s1">&#39;after&#39;</span> <span class="o">=&gt;</span> <span class="p">[]</span>
<span class="p">];</span>
</pre></div>
</div>
<p>Any place you can use a URI in the filter settings, you can use a regular expression or, like in this example, use
an asterisk for a wildcard that will match all characters after that. In this example, any URL&#8217;s starting with <code class="docutils literal"><span class="pre">api/</span></code>
would be exempted from CSRF protection, but the site&#8217;s forms would all be protected. If you need to specify multiple
URI&#8217;s you can use an array of URI patterns:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="k">public</span> <span class="nv">$globals</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;before&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span>
<span class="s1">&#39;csrf&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;except&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;foo/*&#39;</span><span class="p">,</span> <span class="s1">&#39;bar/*&#39;</span><span class="p">]]</span>
<span class="p">],</span>
<span class="s1">&#39;after&#39;</span> <span class="o">=&gt;</span> <span class="p">[]</span>
<span class="p">];</span>
</pre></div>
</div>
</div>
<div class="section" id="methods">
<h3><a class="toc-backref" href="#id7">$methods</a><a class="headerlink" href="#methods" title="Permalink to this headline"></a></h3>
<p>You can apply filters to all requests of a certain HTTP method, like POST, GET, PUT, etc. In this array, you would
specify the method name in lowercase. It&#8217;s value would be an array of filters to run. Unlike the <code class="docutils literal"><span class="pre">$globals</span></code> or the
<code class="docutils literal"><span class="pre">$filters</span></code> properties, these will only run as before filters:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="k">public</span> <span class="nv">$methods</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;post&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="s1">&#39;bar&#39;</span><span class="p">],</span>
<span class="s1">&#39;get&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;baz&#39;</span><span class="p">]</span>
<span class="p">]</span>
</pre></div>
</div>
<p>In addition to the standard HTTP methods, this also supports two special cases: &#8216;cli&#8217;, and &#8216;ajax&#8217;. The names are
self-explanatory here, but &#8216;cli&#8217; would apply to all requests that were run from the command line, while &#8216;ajax&#8217;
would apply to every AJAX request.</p>
</div>
<div class="section" id="filters">
<h3><a class="toc-backref" href="#id8">$filters</a><a class="headerlink" href="#filters" title="Permalink to this headline"></a></h3>
<p>This property is an array of filter aliases. For each alias you can specify before and after arrays that contain
a list of URI patterns that filter should apply to:</p>
<div class="highlight-ci"><div class="highlight"><pre><span></span><span class="k">public</span> <span class="nx">filters</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">&#39;foo&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;before&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;admin/*&#39;</span><span class="p">],</span> <span class="s1">&#39;after&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;users/*&#39;</span><span class="p">]],</span>
<span class="s1">&#39;bar&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;before&#39;</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">&#39;api/*&#39;</span><span class="p">,</span> <span class="s1">&#39;admin/*&#39;</span><span class="p">]]</span>
<span class="p">];</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="provided-filters">
<h2><a class="toc-backref" href="#id9">Provided Filters</a><a class="headerlink" href="#provided-filters" title="Permalink to this headline"></a></h2>
<p>Three filters are bundled with CodeIgniter4: Honeypot, Security, and DebugToolbar.</p>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="message.html" class="btn btn-neutral float-right" title="HTTP Messages" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="routing.html" class="btn btn-neutral" title="URI Routing" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2014-2019 British Columbia Institute of Technology.
Last updated on Feb 18, 2019.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'4.0.0-alpha.5',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: false,
SOURCELINK_SUFFIX: ''
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>