source: trunk/forum/docs/hook_system.html

Last change on this file was 702, checked in by george, 15 years ago
  • Upraveno: Aktualizace fóra.
File size: 24.7 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en" xml:lang="en">
3<head>
4
5<meta http-equiv="content-type" content="text/html; charset=utf-8" />
6<meta http-equiv="content-style-type" content="text/css" />
7<meta http-equiv="content-language" content="en" />
8<meta http-equiv="imagetoolbar" content="no" />
9<meta name="resource-type" content="document" />
10<meta name="distribution" content="global" />
11<meta name="copyright" content="2007 phpBB Group" />
12<meta name="keywords" content="" />
13<meta name="description" content="Hook System explanation" />
14<title>phpBB3 &bull; Hook System</title>
15
16<style type="text/css">
17/* <![CDATA[ */
18
19/*
20 The original "prosilver" theme for phpBB3
21 Created by subBlue design :: http://www.subBlue.com
22*/
23
24* { margin: 0; padding: 0; }
25
26html { font-size: 100%; height: 100%; margin-bottom: 1px; }
27
28body {
29 font-family: Verdana, Helvetica, Arial, sans-serif;
30 color: #828282;
31 background-color: #FFFFFF;
32 font-size: 12px;
33 margin: 0;
34 padding: 12px 0;
35}
36
37img { border-width: 0; }
38
39p {
40 line-height: 1.3em;
41 font-size: 1.1em;
42 margin-bottom: 1.5em;
43}
44
45hr {
46 border: 0 none #FFFFFF;
47 border-top: 1px solid #CCCCCC;
48 height: 1px;
49 margin: 5px 0;
50 display: block;
51 clear: both;
52}
53
54html, body {
55 color: #536482;
56 background-color: #FFFFFF;
57}
58
59#doc-description h1 {
60 font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
61 margin-right: 200px;
62 color: #FFFFFF;
63 margin-top: 15px;
64 font-weight: bold;
65 font-size: 2em;
66 color: #fff;
67}
68
69h1 {
70 font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
71 font-weight: normal;
72 color: #000;
73 font-size: 2em;
74 margin: 0.8em 0 0.2em 0;
75}
76
77h2 {
78 font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
79 font-weight: normal;
80 color: #28313F;
81 font-size: 1.5em;
82 margin: 0.8em 0 0.2em 0;
83}
84
85h3 {
86 font-family: Arial, Helvetica, sans-serif;
87 font-weight: bold;
88 border-bottom: 1px solid #CCCCCC;
89 margin-bottom: 3px;
90 padding-bottom: 2px;
91 font-size: 1.05em;
92 color: #115098;
93 margin-top: 20px;
94}
95
96.good { color: green; }
97.bad { color: red; }
98
99.version {
100 margin-top: 20px;
101 text-align: left;
102 font-size: 70%;
103 color: #006600;
104 border-top: 1px solid #ccc;
105}
106
107code {
108 color: #006600;
109 font-weight: normal;
110 font-family: 'Courier New', monospace;
111 border-color: #D1D7DC;
112 border-width: 1px;
113 border-style: solid;
114 background-color: #FAFAFA;
115}
116
117#wrap {
118 padding: 0 20px;
119 min-width: 650px;
120}
121
122#simple-wrap {
123 padding: 6px 10px;
124}
125
126#page-body {
127 margin: 4px 0;
128 clear: both;
129}
130
131#page-footer {
132 clear: both;
133}
134
135#logo {
136 float: left;
137 width: auto;
138 padding: 10px 13px 0 10px;
139}
140
141a#logo:hover {
142 text-decoration: none;
143}
144
145#doc-description {
146 float: left;
147 width: 70%;
148}
149
150#doc-description h1 {
151 margin-right: 0;
152}
153
154.headerbar {
155 background: #ebebeb none repeat-x 0 0;
156 color: #FFFFFF;
157 margin-bottom: 4px;
158 padding: 0 5px;
159}
160
161span.corners-top, span.corners-bottom, span.corners-top span, span.corners-bottom span {
162 font-size: 1px;
163 line-height: 1px;
164 display: block;
165 height: 5px;
166 background-repeat: no-repeat;
167}
168
169span.corners-top {
170 background-image: none;
171 background-position: 0 0;
172 margin: 0 -5px;
173}
174
175span.corners-top span {
176 background-image: none;
177 background-position: 100% 0;
178}
179
180span.corners-bottom {
181 background-image: none;
182 background-position: 0 100%;
183 margin: 0 -5px;
184 clear: both;
185}
186
187span.corners-bottom span {
188 background-image: none;
189 background-position: 100% 100%;
190}
191
192.paragraph {
193 padding: 0 10px;
194 margin-bottom: 4px;
195 background-repeat: no-repeat;
196 background-position: 100% 0;
197 background-color: #ECF3F7;
198}
199
200.paragraph:target .content {
201 color: #000000;
202}
203
204.paragraph:target h3 a {
205 color: #000000;
206}
207
208.content {
209 color: #333333;
210}
211
212.content h2, .panel h2 {
213 color: #115098;
214 border-bottom-color: #CCCCCC;
215}
216
217a:link { color: #898989; text-decoration: none; }
218a:visited { color: #898989; text-decoration: none; }
219a:hover { color: #d3d3d3; text-decoration: underline; }
220a:active { color: #d2d2d2; text-decoration: none; }
221
222hr {
223 border-color: #FFFFFF;
224 border-top-color: #CCCCCC;
225}
226
227.menu {
228 background-color: #cadceb;
229}
230
231.headerbar {
232 background-color: #12A3EB;
233 background-image: url("bg_header.gif");
234 color: #FFFFFF;
235}
236
237.panel {
238 background-color: #ECF1F3;
239 color: #28313F;
240}
241
242
243span.corners-top {
244 background-image: url("corners_left.png");
245}
246
247span.corners-top span {
248 background-image: url("corners_right.png");
249}
250
251span.corners-bottom {
252 background-image: url("corners_left.png");
253}
254
255span.corners-bottom span {
256 background-image: url("corners_right.png");
257}
258
259.error {
260 color: #BC2A4D;
261}
262
263a:link { color: #105289; }
264a:visited { color: #105289; }
265a:hover { color: #D31141; }
266a:active { color: #368AD2; }
267
268.paragraph span.corners-top, .paragraph span.corners-bottom {
269 margin: 0 -10px;
270}
271
272.content {
273 padding: 0;
274 line-height: 1.48em;
275 color: #333333;
276}
277
278.content h2, .panel h2 {
279 color: #115098;
280 border-bottom-color: #CCCCCC;
281}
282
283.notice {
284 border-top-color: #CCCCCC;
285}
286
287.codebox {
288 padding: 3px;
289 background-color: #FFFFFF;
290 border: 1px solid #C9D2D8;
291 font-size: 1em;
292 margin-bottom: 10px;
293 display: block;
294 font: 0.9em Monaco, "Andale Mono","Courier New", Courier, mono;
295 line-height: 1.3em;
296}
297
298* html hr { margin: 0; }
299* html span.corners-top, * html span.corners-bottom { background-image: url("corners_left.gif"); }
300* html span.corners-top span, * html span.corners-bottom span { background-image: url("corners_right.gif"); }
301
302.back2top {
303 clear: both;
304 height: 11px;
305 text-align: right;
306}
307
308.content ol {
309 margin-left: 25px;
310}
311
312/* ]]> */
313</style>
314
315</head>
316
317<body id="phpbb" class="section-docs">
318
319<div id="wrap">
320 <a id="top" name="top" accesskey="t"></a>
321 <div id="page-header">
322 <div class="headerbar">
323 <div class="inner"><span class="corners-top"><span></span></span>
324
325 <div id="doc-description">
326 <a href="../index.php" id="logo"><img src="site_logo.gif" alt="" /></a>
327 <h1>Hook System</h1>
328 <p>This is an explanation of how to use the phpBB3 hook system.</p>
329 <p style="display: none;"><a href="#start_here">Skip</a></p>
330 </div>
331
332 <span class="corners-bottom"><span></span></span></div>
333 </div>
334 </div>
335
336 <a name="start_here"></a>
337
338 <div id="page-body">
339
340 <h1>Hook System</h1>
341
342 <div class="paragraph menu">
343 <div class="inner"><span class="corners-top"><span></span></span>
344
345 <div class="content">
346
347 <ol>
348 <li><a href="#intro">Introduction</a></li>
349 <li><a href="#use">Allow hooks in functions/methods</a></li>
350 <li><a href="#register">Registering hooks</a></li>
351 <li><a href="#return">Result returning</a></li>
352 <li><a href="#embed">Embedding your hook files/classes/methods</a></li>
353 <li><a href="#disclaimer">Copyright and disclaimer</a></li>
354 </ol>
355
356 </div>
357
358 <span class="corners-bottom"><span></span></span></div>
359 </div>
360
361 <hr />
362
363 <a name="intro"></a><h2>1. Introduction</h2>
364
365 <div class="paragraph">
366 <div class="inner"><span class="corners-top"><span></span></span>
367
368 <div class="content">
369
370<h3>What is it?</h3>
371
372<p>The hook system allows applicaton and mod developers to hook into phpBB's or their own functions.</p>
373
374<h3>Pre-defined hookable phpBB3 functions</h3>
375
376<p>In phpBB3 there are four functions you are able to hook into with your custom functions:</p>
377
378<p><code>phpbb_user_session_handler();</code> which is called within user::setup after the session and the user object is correctly initialized.<br />
379<code>append_sid($url, $params = false, $is_amp = true, $session_id = false);</code> which is called for building urls (appending the session id)<br />
380<code>$template-&gt;display($handle, $include_once = true);</code> which is called directly before outputting the (not-yet-compiled) template.<br />
381<code>exit_handler();</code> which is called at the very end of phpBB3's execution.</p>
382
383<p>There are also valid external constants you may want to use if you embed phpBB3 into your application:</p>
384
385<div class="codebox"><pre>
386PHPBB_MSG_HANDLER (overwrite message handler)
387PHPBB_DB_NEW_LINK (overwrite new_link parameter for sql_connect)
388PHPBB_ROOT_PATH (overwrite $phpbb_root_path)
389PHPBB_ADMIN_PATH (overwrite $phpbb_admin_path)
390PHPBB_USE_BOARD_URL_PATH (use generate_board_url() for image paths instead of $phpbb_root_path)
391</pre></div>
392
393<p>If the <code>PHPBB_USE_BOARD_URL_PATH</code> constant is set to true, phpBB uses generate_board_url() (this will return the boards url with the script path included) on all instances where web-accessible images are loaded. The exact locations are:</p>
394
395<ul>
396 <li>/includes/session.php - user::img()</li>
397 <li>/includes/functions_content.php - smiley_text()</li>
398</ul>
399
400<p>Path locations for the following template variables are affected by this too:</p>
401
402<ul>
403 <li>{T_THEME_PATH} - styles/xxx/theme</li>
404 <li>{T_TEMPLATE_PATH} - styles/xxx/template</li>
405 <li>{T_SUPER_TEMPLATE_PATH} - styles/xxx/template</li>
406 <li>{T_IMAGESET_PATH} - styles/xxx/imageset</li>
407 <li>{T_IMAGESET_LANG_PATH} - styles/xxx/imageset/yy</li>
408 <li>{T_IMAGES_PATH} - images/</li>
409 <li>{T_SMILIES_PATH} - $config['smilies_path']/</li>
410 <li>{T_AVATAR_PATH} - $config['avatar_path']/</li>
411 <li>{T_AVATAR_GALLERY_PATH} - $config['avatar_gallery_path']/</li>
412 <li>{T_ICONS_PATH} - $config['icons_path']/</li>
413 <li>{T_RANKS_PATH} - $config['ranks_path']/</li>
414 <li>{T_UPLOAD_PATH} - $config['upload_path']/</li>
415 <li>{T_STYLESHEET_LINK} - styles/xxx/theme/stylesheet.css (or link to style.php if css is parsed dynamically)</li>
416 <li>New template variable {BOARD_URL} for the board url + script path.</li>
417</ul>
418
419
420 </div>
421
422 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
423
424 <span class="corners-bottom"><span></span></span></div>
425 </div>
426
427 <a name="use"></a><h2>2. Allow hooks in functions/methods</h2>
428
429 <div class="paragraph">
430 <div class="inner"><span class="corners-top"><span></span></span>
431
432 <div class="content">
433
434<p>The following examples explain how phpBB3 utilize the in-build hook system. You will be more interested in registering your hooks, but showing you this may help you understand the system better along the way.</p>
435
436<p>First of all, this is how a function need to be layed out if you want to allow it to be hookable...</p>
437
438<div class="codebox"><pre>
439function my_own_function($my_first_parameter, $my_second_parameter)
440{
441 global $phpbb_hook;
442
443 if ($phpbb_hook-&gt;call_hook(__FUNCTION__, $my_first_parameter, $my_second_parameter))
444 {
445 if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
446 {
447 return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
448 }
449 }
450
451 [YOUR CODE HERE]
452}
453</pre></div>
454
455<p>Above, the call_hook function should always be mapping your function call... in regard to the number of parameters passed.</p>
456
457<p>This is how you could make a method being hookable...</p>
458
459<div class="codebox"><pre>
460class my_hookable_object
461{
462 function hook_me($my_first_parameter, $my_second_parameter)
463 {
464 global $phpbb_hook;
465
466 if ($phpbb_hook-&gt;call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
467 {
468 if ($phpbb_hook-&gt;hook_return(array(__CLASS__, __FUNCTION__)))
469 {
470 return $phpbb_hook-&gt;hook_return_result(array(__CLASS__, __FUNCTION__));
471 }
472 }
473
474 [YOUR CODE HERE]
475 }
476}
477</pre></div>
478
479<p>The only difference about calling it is the way you define the first parameter. For a function it is only <code>__FUNCTION__</code>, for a method it is <code>array(__CLASS__, __FUNCTION__)</code>. In PHP4 __CLASS__ is always returning the class in lowercase.</p>
480
481<p>Now, in phpBB there are some pre-defined hooks available, but how do you make your own hookable function available (and therefore allowing others to hook into it)? For this, there is the add_hook() method:</p>
482
483<div class="codebox"><pre>
484// Adding your own hookable function:
485$phpbb_hook-&gt;add_hook('my_own_function');
486
487// Adding your own hookable method:
488$phpbb_hook-&gt;add_hook(array('my_hookable_object', 'hook_me'));
489</pre></div>
490
491<p>You are also able to remove the possibility of hooking a function/method by calling <code>$phpbb_hook-&gt;remove_hook()</code> with the same parameters as add_hook().<br />
492This comes in handy if you want to force some hooks not to be called - at all.</p>
493
494 </div>
495
496 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
497
498 <span class="corners-bottom"><span></span></span></div>
499 </div>
500
501 <a name="register"></a><h2>3. Registering hooks</h2>
502
503 <div class="paragraph">
504 <div class="inner"><span class="corners-top"><span></span></span>
505
506 <div class="content">
507
508 <h3>Registering hooks</h3>
509
510<p>Now to actually defining your functions which should be called. For this we take the append_sid() function as an example (this function is able to be hooked by default). We create two classes, one being static and a function:</p>
511
512<div class="codebox"><pre>
513class my_append_sid_class
514{
515 // Our functions
516 function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
517 {
518 // Get possible previous results
519 $result = $hook-&gt;previous_hook_result('append_sid');
520
521 return $result['result'] . '&lt;br /&gt;And i was the second one.';
522 }
523}
524
525// Yet another class :o
526class my_second_append_sid_class
527{
528 function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
529 {
530 // Get possible previous results
531 $result = $hook-&gt;previous_hook_result('append_sid');
532
533 echo $result['result'] . '&lt;br /&gt;I was called as the third one.';
534 }
535}
536
537// And a normal function
538function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
539{
540 // Get possible previous results
541 $result = $hook-&gt;previous_hook_result('append_sid');
542
543 return 'I was called as the first one';
544}
545
546// Initializing the second class
547$my_second_append_sid_class = new my_second_append_sid_class();
548</pre></div>
549
550<p>Make sure you add the same parameters to your function as is defined for the hookable function with one exception: The first variable is always <code>&amp;$hook</code>... this is the hook object itself you are able to operate on.</p>
551
552<p>Now we register the hooks one by one with the <code>$phpbb_hook-&gt;register()</code> method:</p>
553
554<div class="codebox"><pre>
555// Now, we register our append_sid &quot;replacements&quot; in a stacked way...
556// Registering the function (this is called first)
557$phpbb_hook-&gt;register('append_sid', 'my_append_sid');
558
559// Registering the first class
560$phpbb_hook-&gt;register('append_sid', array('my_append_sid_class', 'my_append_sid'));
561$phpbb_hook-&gt;register('append_sid', array(&amp;$my_second_append_sid_class, 'my_append_sid'));
562</pre></div>
563
564<p>With this you are even able to make your own functions that are already hooked itself being hooked again...</p>
565
566<div class="codebox"><pre>
567// Registering hook, which will be called
568$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid');
569
570// Add hook to our called hook function
571$phpbb_hook-&gt;add_hook('my_own_append_sid');
572
573// Register added hook
574$phpbb_hook-&gt;register('my_own_append_sid', 'also_my_own_append_sid');
575</pre></div>
576
577 <h3>Special treatment/chains</h3>
578
579 <p>The <code>register</code> method is able to take a third argument to specify a special 'chain' mode. The valid modes are <code>first</code>, <code>last</code> and <code>standalone</code></p>
580
581 <p><code>$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid', 'first')</code> would make sure that the function is called in the beginning of the chain. It is possible that more than one function is called within the first block - here the FIFO principle is used.</p>
582
583 <p><code>$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid', 'last')</code> would make sure that the function is called at the very end of the chain. It is possible that more than one function is called within the last block - here the FIFO principle is used.</p>
584
585 <p><code>$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid', 'standalone')</code> makes sure only the defined function is called. All other functions are removed from the chain and no other functions are added to it later on. If two applications try to trigger the standalone mode a PHP notice will be printed and the second function being discarded.</p>
586
587 <h3>Only allowing hooks for some objects</h3>
588
589 <p>Because the hook system is not able to differate between initialized objects and only operate on the class, you need to solve this on the code level.</p>
590
591 <p>One possibility would be to use a property:</p>
592
593 <div class="codebox"><pre>
594class my_hookable_object
595{
596 function blabla()
597 {
598 }
599}
600
601class my_hookable_object2 extends my_hookable_object
602{
603 var $call_hook = true;
604
605 function hook_me($my_first_parameter, $my_second_parameter)
606 {
607 if ($this-&gt;call_hook)
608 {
609 global $phpbb_hook;
610
611 if ($phpbb_hook-&gt;call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
612 {
613 if ($phpbb_hook-&gt;hook_return(array(__CLASS__, __FUNCTION__)))
614 {
615 return $phpbb_hook-&gt;hook_return_result(array(__CLASS__, __FUNCTION__));
616 }
617 }
618 }
619
620 return 'not hooked';
621 }
622}
623
624function hooking(&amp;$hook, $first, $second)
625{
626 return 'hooked';
627}
628
629$first_object = new my_hookable_object2();
630$second_object = new my_hookable_object2();
631
632$phpbb_hook-&gt;add_hook(array('my_hookable_object2', 'hook_me'));
633
634$phpbb_hook-&gt;register(array('my_hookable_object2', 'hook_me'), 'hooking');
635
636// Do not call the hook for $first_object
637$first_object-&gt;call_hook = false;
638
639echo $first_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
640echo $second_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
641</pre></div>
642
643<p>OUTPUT:</p>
644
645<div class="codebox"><pre>
646not hooked
647hooked
648</pre></div>
649
650 <p>A different possibility would be using a function variable (which could be left out on passing the function variables to the hook):</p>
651
652 <div class="codebox"><pre>
653class my_hookable_object
654{
655 function blabla()
656 {
657 }
658}
659
660class my_hookable_object2 extends my_hookable_object
661{
662 function hook_me($my_first_parameter, $my_second_parameter, $hook_me = true)
663 {
664 if ($hook_me)
665 {
666 global $phpbb_hook;
667
668 if ($phpbb_hook-&gt;call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
669 {
670 if ($phpbb_hook-&gt;hook_return(array(__CLASS__, __FUNCTION__)))
671 {
672 return $phpbb_hook-&gt;hook_return_result(array(__CLASS__, __FUNCTION__));
673 }
674 }
675 }
676
677 return 'not hooked';
678 }
679}
680
681function hooking(&amp;$hook, $first, $second)
682{
683 return 'hooked';
684}
685
686$first_object = new my_hookable_object2();
687$second_object = new my_hookable_object2();
688
689$phpbb_hook-&gt;add_hook(array('my_hookable_object2', 'hook_me'));
690
691$phpbb_hook-&gt;register(array('my_hookable_object2', 'hook_me'), 'hooking');
692
693echo $first_object-&gt;hook_me('first', 'second', false) . '&lt;br /&gt;';
694echo $second_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
695 </pre></div>
696
697 <p>OUTPUT:</p>
698
699 <div class="codebox"><pre>
700not hooked
701hooked
702 </pre></div>
703
704 </div>
705
706 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
707
708 <span class="corners-bottom"><span></span></span></div>
709 </div>
710
711 <a name="return"></a><h2>4. Result returning</h2>
712
713 <div class="paragraph">
714 <div class="inner"><span class="corners-top"><span></span></span>
715
716 <div class="content">
717
718<p>Generally, the distinction has to be made if a function returns the result obtained from the called function or continue the execution. Based on the needs of the application this may differ. Therefore, the function returns the results only if the called hook function is returning a result.</p>
719
720<h3>Case 1 - Returning the result</h3>
721
722<p>Imagine the following function supporting hooks:</p>
723
724<div class="codebox"><pre>
725function append_sid($url, $params = false, $is_amp = true, $session_id = false)
726{
727 global $_SID, $_EXTRA_URL, $phpbb_hook;
728
729 // Developers using the hook function need to globalise the $_SID and $_EXTRA_URL on their own and also handle it appropiatly.
730 // They could mimick most of what is within this function
731 if ($phpbb_hook-&gt;call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
732 {
733 if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
734 {
735 return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
736 }
737 }
738
739 [...]
740}
741</pre></div>
742
743<p>Now, the following function is yours. Since you return a value, the append_sid() function itself is returning it as is:</p>
744
745<div class="codebox"><pre>
746// The function called
747function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
748{
749 // Get possible previous results
750 $result = $hook-&gt;previous_hook_result('append_sid');
751
752 return 'Since i return something the append_sid() function will return my result.';
753}
754</pre></div>
755
756<p>To be able to get the results returned from functions higher in the change the <code>previous_hook_result()</code> method should always be used, it returns an <code>array('result' => [your result])</code> construct.</p>
757
758<h3>Case 2 - Not Returning any result</h3>
759
760<p>Sometimes applications want to return nothing and therefore force the underlying function to continue it's execution:</p>
761
762<div class="codebox"><pre>
763function append_sid($url, $params = false, $is_amp = true, $session_id = false)
764{
765 global $_SID, $_EXTRA_URL, $phpbb_hook;
766
767 // Developers using the hook function need to globalise the $_SID and $_EXTRA_URL on their own and also handle it appropiatly.
768 // They could mimick most of what is within this function
769 if ($phpbb_hook-&gt;call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
770 {
771 if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
772 {
773 return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
774 }
775 }
776
777 [...]
778}
779
780// The function called
781function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
782{
783 // Get possible previous results
784 $result = $hook-&gt;previous_hook_result('append_sid');
785
786 [...]
787
788 // I only rewrite some variables, but return nothing. Therefore, the append_sid() function will not return my (non)result.
789}
790</pre></div>
791
792<p>Please Note: The decision to return or not return is solely made of the very last function call within the hook chain. An example:</p>
793
794<div class="codebox"><pre>
795// The function called
796function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
797{
798 // Get possible previous results
799 $result = $hook-&gt;previous_hook_result('append_sid');
800
801 // $result is not filled
802
803 return 'FILLED';
804}
805
806// This function is registered too and gets executed after my_append_sid()
807function my_own_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
808{
809 $result = $hook->previous_hook_result('append_sid');
810
811 // $result is actually filled with $result['result'] = 'FILLED'
812 // But i return nothing, therefore append_sid() continues it's execution.
813}
814
815// The way both functions are registered.
816$phpbb_hook->register('append_sid', 'my_append_sid');
817$phpbb_hook->register('append_sid', 'my_own_append_sid');
818</pre></div>
819
820 </div>
821
822 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
823
824 <span class="corners-bottom"><span></span></span></div>
825 </div>
826
827 <a name="embed"></a><h2>5. Embedding your hook files/classes/methods</h2>
828
829 <div class="paragraph">
830 <div class="inner"><span class="corners-top"><span></span></span>
831
832 <div class="content">
833
834<p>There are basically two methods you are able to choose from:</p>
835
836<p>1) Add a file to includes/hooks/. The file need to be prefixed by <code>hook_</code>. This file is included within common.php, you are able to register your hooks, include other files or functions, etc. It is advised to only include other files if needed (within a function call for example).</p>
837
838<p>Please be aware that you need to purge your cache within the ACP to make your newly placed file available to phpBB3.</p>
839
840<p>2) The second method is meant for those wanting to wrap phpBB3 without placing a custom file to the hooks directory. This is mostly done by including phpBB's files within the application file. To be able to register your hooks you need to create a function within your application:</p>
841
842<div class="codebox"><pre>
843// My function which gets executed within the hooks constuctor
844function phpbb_hook_register(&amp;$hook)
845{
846 $hook-&gt;register('append_sid', 'my_append_sid');
847}
848
849[...]
850</pre></div>
851
852<p>You should get the idea. ;)</p>
853
854 </div>
855
856 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
857
858 <span class="corners-bottom"><span></span></span></div>
859 </div>
860
861 <a name="disclaimer"></a><h2>6. Copyright and disclaimer</h2>
862
863 <div class="paragraph">
864 <div class="inner"><span class="corners-top"><span></span></span>
865
866 <div class="content">
867
868 <p>This application is opensource software released under the <a href="http://opensource.org/licenses/gpl-license.php">GPL</a>. Please see source code and the docs directory for more details. This package and its contents are Copyright (c) 2000, 2002, 2005, 2007 <a href="http://www.phpbb.com/">phpBB Group</a>, All Rights Reserved.</p>
869
870 </div>
871
872 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
873
874 <span class="corners-bottom"><span></span></span></div>
875 </div>
876
877 <div id="page-footer">
878 <div class="version">$Id$</div>
879 </div>
880</div></div>
881
882<div>
883 <a id="bottom" name="bottom" accesskey="z"></a>
884</div>
885
886</body>
887</html>
Note: See TracBrowser for help on using the repository browser.