~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to www/php/phpBB3/docs/hook_system.html

  • Committer: William Grant
  • Date: 2009-02-23 23:47:02 UTC
  • mfrom: (1099.1.211 new-dispatch)
  • Revision ID: grantw@unimelb.edu.au-20090223234702-db4b1llly46ignwo
Merge from lp:~ivle-dev/ivle/new-dispatch.

Pretty much everything changes. Reread the setup docs. Backup your databases.
Every file is now in a different installed location, the configuration system
is rewritten, the dispatch system is rewritten, URLs are different, the
database is different, worksheets and exercises are no longer on the
filesystem, we use a templating engine, jail service protocols are rewritten,
we don't repeat ourselves, we have authorization rewritten, phpBB is gone,
and probably lots of other things that I cannot remember.

This is certainly the biggest commit I have ever made, and hopefully
the largest I ever will.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
 
<!--
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
 
 
26
 
html { font-size: 100%; height: 100%; margin-bottom: 1px; }
27
 
 
28
 
body {
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
 
 
37
 
img { border-width: 0; }
38
 
 
39
 
p {
40
 
        line-height: 1.3em;
41
 
        font-size: 1.1em;
42
 
        margin-bottom: 1.5em;
43
 
}
44
 
 
45
 
hr {
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
 
 
54
 
html, 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
 
 
69
 
h1 {
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
 
 
77
 
h2 {
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
 
 
85
 
h3 {
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
 
 
107
 
code { 
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
 
 
141
 
a#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
 
 
161
 
span.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
 
 
169
 
span.corners-top {
170
 
        background-image: none;
171
 
        background-position: 0 0;
172
 
        margin: 0 -5px;
173
 
}
174
 
 
175
 
span.corners-top span {
176
 
        background-image: none;
177
 
        background-position: 100% 0;
178
 
}
179
 
 
180
 
span.corners-bottom {
181
 
        background-image: none;
182
 
        background-position: 0 100%;
183
 
        margin: 0 -5px;
184
 
        clear: both;
185
 
}
186
 
 
187
 
span.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
 
 
217
 
a:link  { color: #898989; text-decoration: none; }
218
 
a:visited       { color: #898989; text-decoration: none; }
219
 
a:hover { color: #d3d3d3; text-decoration: underline; }
220
 
a:active        { color: #d2d2d2; text-decoration: none; }
221
 
 
222
 
hr {
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
 
 
243
 
span.corners-top {
244
 
        background-image: url("corners_left.png");
245
 
}
246
 
 
247
 
span.corners-top span {
248
 
        background-image: url("corners_right.png");
249
 
}
250
 
 
251
 
span.corners-bottom {
252
 
        background-image: url("corners_left.png");
253
 
}
254
 
 
255
 
span.corners-bottom span {
256
 
        background-image: url("corners_right.png");
257
 
}
258
 
 
259
 
.error {
260
 
        color: #BC2A4D;
261
 
}
262
 
 
263
 
a:link  { color: #105289; }
264
 
a:visited       { color: #105289; }
265
 
a:hover { color: #D31141; }
266
 
a: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>
386
 
PHPBB_MSG_HANDLER (overwrite message handler)
387
 
PHPBB_DB_NEW_LINK (overwrite new_link parameter for sql_connect)
388
 
PHPBB_ROOT_PATH   (overwrite $phpbb_root_path)
389
 
PHPBB_ADMIN_PATH  (overwrite $phpbb_admin_path)
390
 
</pre></div>
391
 
 
392
 
                </div>
393
 
 
394
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
395
 
 
396
 
                <span class="corners-bottom"><span></span></span></div>
397
 
        </div>
398
 
 
399
 
        <a name="use"></a><h2>2. Allow hooks in functions/methods</h2>
400
 
 
401
 
        <div class="paragraph">
402
 
                <div class="inner"><span class="corners-top"><span></span></span>
403
 
 
404
 
                <div class="content">
405
 
 
406
 
<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>
407
 
 
408
 
<p>First of all, this is how a function need to be layed out if you want to allow it to be hookable...</p>
409
 
 
410
 
<div class="codebox"><pre>
411
 
function my_own_function($my_first_parameter, $my_second_parameter)
412
 
{
413
 
        global $phpbb_hook;
414
 
 
415
 
        if ($phpbb_hook-&gt;call_hook(__FUNCTION__, $my_first_parameter, $my_second_parameter))
416
 
        {
417
 
                if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
418
 
                {
419
 
                        return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
420
 
                }
421
 
        }
422
 
 
423
 
        [YOUR CODE HERE]
424
 
}
425
 
</pre></div>
426
 
 
427
 
<p>Above, the call_hook function should always be mapping your function call... in regard to the number of parameters passed.</p>
428
 
 
429
 
<p>This is how you could make a method being hookable...</p>
430
 
 
431
 
<div class="codebox"><pre>
432
 
class my_hookable_object
433
 
{
434
 
        function hook_me($my_first_parameter, $my_second_parameter)
435
 
        {
436
 
                global $phpbb_hook;
437
 
 
438
 
                if ($phpbb_hook-&gt;call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
439
 
                {
440
 
                        if ($phpbb_hook-&gt;hook_return(array(__CLASS__, __FUNCTION__)))
441
 
                        {
442
 
                                return $phpbb_hook-&gt;hook_return_result(array(__CLASS__, __FUNCTION__));
443
 
                        }
444
 
                }
445
 
 
446
 
                [YOUR CODE HERE]
447
 
        }
448
 
}
449
 
</pre></div>
450
 
 
451
 
<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>
452
 
 
453
 
<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>
454
 
 
455
 
<div class="codebox"><pre>
456
 
// Adding your own hookable function:
457
 
$phpbb_hook-&gt;add_hook('my_own_function');
458
 
 
459
 
// Adding your own hookable method:
460
 
$phpbb_hook-&gt;add_hook(array('my_hookable_object', 'hook_me'));
461
 
</pre></div>
462
 
 
463
 
<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 />
464
 
This comes in handy if you want to force some hooks not to be called - at all.</p>
465
 
 
466
 
                </div>
467
 
 
468
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
469
 
 
470
 
                <span class="corners-bottom"><span></span></span></div>
471
 
        </div>
472
 
 
473
 
        <a name="register"></a><h2>3. Registering hooks</h2>
474
 
 
475
 
        <div class="paragraph">
476
 
                <div class="inner"><span class="corners-top"><span></span></span>
477
 
 
478
 
                <div class="content">
479
 
 
480
 
                <h3>Registering hooks</h3>
481
 
 
482
 
<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>
483
 
 
484
 
<div class="codebox"><pre>
485
 
class my_append_sid_class
486
 
{
487
 
        // Our functions
488
 
        function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
489
 
        {
490
 
                // Get possible previous results
491
 
                $result = $hook-&gt;previous_hook_result('append_sid');
492
 
 
493
 
                return $result['result'] . '&lt;br /&gt;And i was the second one.';
494
 
        }
495
 
}
496
 
 
497
 
// Yet another class :o
498
 
class my_second_append_sid_class
499
 
{
500
 
        function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
501
 
        {
502
 
                // Get possible previous results
503
 
                $result = $hook-&gt;previous_hook_result('append_sid');
504
 
 
505
 
                echo $result['result'] . '&lt;br /&gt;I was called as the third one.';
506
 
        }
507
 
}
508
 
 
509
 
// And a normal function
510
 
function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
511
 
{
512
 
        // Get possible previous results
513
 
        $result = $hook-&gt;previous_hook_result('append_sid');
514
 
 
515
 
        return 'I was called as the first one';
516
 
}
517
 
 
518
 
// Initializing the second class
519
 
$my_second_append_sid_class = new my_second_append_sid_class();
520
 
</pre></div>
521
 
 
522
 
<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>
523
 
 
524
 
<p>Now we register the hooks one by one with the <code>$phpbb_hook-&gt;register()</code> method:</p>
525
 
 
526
 
<div class="codebox"><pre>
527
 
// Now, we register our append_sid &quot;replacements&quot; in a stacked way...
528
 
// Registering the function (this is called first)
529
 
$phpbb_hook-&gt;register('append_sid', 'my_append_sid');
530
 
 
531
 
// Registering the first class
532
 
$phpbb_hook-&gt;register('append_sid', array('my_append_sid_class', 'my_append_sid'));
533
 
$phpbb_hook-&gt;register('append_sid', array(&amp;$my_second_append_sid_class, 'my_append_sid'));
534
 
</pre></div>
535
 
 
536
 
<p>With this you are even able to make your own functions that are already hooked itself being hooked again...</p>
537
 
 
538
 
<div class="codebox"><pre>
539
 
// Registering hook, which will be called
540
 
$phpbb_hook-&gt;register('append_sid', 'my_own_append_sid');
541
 
 
542
 
// Add hook to our called hook function
543
 
$phpbb_hook-&gt;add_hook('my_own_append_sid');
544
 
 
545
 
// Register added hook
546
 
$phpbb_hook-&gt;register('my_own_append_sid', 'also_my_own_append_sid');
547
 
</pre></div>
548
 
 
549
 
                <h3>Special treatment/chains</h3>
550
 
 
551
 
                <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>
552
 
 
553
 
                <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>
554
 
 
555
 
                <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>
556
 
 
557
 
                <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>
558
 
 
559
 
                <h3>Only allowing hooks for some objects</h3>
560
 
 
561
 
                <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>
562
 
 
563
 
                <p>One possibility would be to use a property:</p>
564
 
 
565
 
                <div class="codebox"><pre>
566
 
class my_hookable_object
567
 
{
568
 
        function blabla()
569
 
        {
570
 
        }
571
 
}
572
 
 
573
 
class my_hookable_object2 extends my_hookable_object
574
 
{
575
 
        var $call_hook = true;
576
 
 
577
 
        function hook_me($my_first_parameter, $my_second_parameter)
578
 
        {
579
 
                if ($this-&gt;call_hook)
580
 
                {
581
 
                        global $phpbb_hook;
582
 
 
583
 
                        if ($phpbb_hook-&gt;call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
584
 
                        {
585
 
                                if ($phpbb_hook-&gt;hook_return(array(__CLASS__, __FUNCTION__)))
586
 
                                {
587
 
                                        return $phpbb_hook-&gt;hook_return_result(array(__CLASS__, __FUNCTION__));
588
 
                                }
589
 
                        }
590
 
                }
591
 
 
592
 
                return 'not hooked';
593
 
        }
594
 
}
595
 
 
596
 
function hooking(&amp;$hook, $first, $second)
597
 
{
598
 
        return 'hooked';
599
 
}
600
 
 
601
 
$first_object = new my_hookable_object2();
602
 
$second_object = new my_hookable_object2();
603
 
 
604
 
$phpbb_hook-&gt;add_hook(array('my_hookable_object2', 'hook_me'));
605
 
 
606
 
$phpbb_hook-&gt;register(array('my_hookable_object2', 'hook_me'), 'hooking');
607
 
 
608
 
// Do not call the hook for $first_object
609
 
$first_object-&gt;call_hook = false;
610
 
 
611
 
echo $first_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
612
 
echo $second_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
613
 
</pre></div>
614
 
 
615
 
<p>OUTPUT:</p>
616
 
 
617
 
<div class="codebox"><pre>
618
 
not hooked
619
 
hooked 
620
 
</pre></div>
621
 
 
622
 
                <p>A different possibility would be using a function variable (which could be left out on passing the function variables to the hook):</p>
623
 
 
624
 
                <div class="codebox"><pre>
625
 
class my_hookable_object
626
 
{
627
 
        function blabla()
628
 
        {
629
 
        }
630
 
}
631
 
 
632
 
class my_hookable_object2 extends my_hookable_object
633
 
{
634
 
        function hook_me($my_first_parameter, $my_second_parameter, $hook_me = true)
635
 
        {
636
 
                if ($hook_me)
637
 
                {
638
 
                        global $phpbb_hook;
639
 
 
640
 
                        if ($phpbb_hook-&gt;call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))
641
 
                        {
642
 
                                if ($phpbb_hook-&gt;hook_return(array(__CLASS__, __FUNCTION__)))
643
 
                                {
644
 
                                        return $phpbb_hook-&gt;hook_return_result(array(__CLASS__, __FUNCTION__));
645
 
                                }
646
 
                        }
647
 
                }
648
 
 
649
 
                return 'not hooked';
650
 
        }
651
 
}
652
 
 
653
 
function hooking(&amp;$hook, $first, $second)
654
 
{
655
 
        return 'hooked';
656
 
}
657
 
 
658
 
$first_object = new my_hookable_object2();
659
 
$second_object = new my_hookable_object2();
660
 
 
661
 
$phpbb_hook-&gt;add_hook(array('my_hookable_object2', 'hook_me'));
662
 
 
663
 
$phpbb_hook-&gt;register(array('my_hookable_object2', 'hook_me'), 'hooking');
664
 
 
665
 
echo $first_object-&gt;hook_me('first', 'second', false) . '&lt;br /&gt;';
666
 
echo $second_object-&gt;hook_me('first', 'second') . '&lt;br /&gt;';
667
 
                </pre></div>
668
 
 
669
 
                <p>OUTPUT:</p>
670
 
 
671
 
                <div class="codebox"><pre>
672
 
not hooked
673
 
hooked 
674
 
                </pre></div>
675
 
 
676
 
                </div>
677
 
 
678
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
679
 
 
680
 
                <span class="corners-bottom"><span></span></span></div>
681
 
        </div>
682
 
 
683
 
        <a name="return"></a><h2>4. Result returning</h2>
684
 
 
685
 
        <div class="paragraph">
686
 
                <div class="inner"><span class="corners-top"><span></span></span>
687
 
 
688
 
                <div class="content">
689
 
 
690
 
<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>
691
 
 
692
 
<h3>Case 1 - Returning the result</h3>
693
 
 
694
 
<p>Imagine the following function supporting hooks:</p>
695
 
 
696
 
<div class="codebox"><pre>
697
 
function append_sid($url, $params = false, $is_amp = true, $session_id = false)
698
 
{
699
 
        global $_SID, $_EXTRA_URL, $phpbb_hook;
700
 
 
701
 
        // Developers using the hook function need to globalise the $_SID and $_EXTRA_URL on their own and also handle it appropiatly.
702
 
        // They could mimick most of what is within this function
703
 
        if ($phpbb_hook-&gt;call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
704
 
        {
705
 
                if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
706
 
                {
707
 
                        return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
708
 
                }
709
 
        }
710
 
 
711
 
        [...]
712
 
}
713
 
</pre></div>
714
 
 
715
 
<p>Now, the following function is yours. Since you return a value, the append_sid() function itself is returning it as is:</p>
716
 
 
717
 
<div class="codebox"><pre>
718
 
// The function called
719
 
function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
720
 
{
721
 
        // Get possible previous results
722
 
        $result = $hook-&gt;previous_hook_result('append_sid');
723
 
 
724
 
        return 'Since i return something the append_sid() function will return my result.';
725
 
}
726
 
</pre></div>
727
 
 
728
 
<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>
729
 
 
730
 
<h3>Case 2 - Not Returning any result</h3>
731
 
 
732
 
<p>Sometimes applications want to return nothing and therefore force the underlying function to continue it's execution:</p>
733
 
 
734
 
<div class="codebox"><pre>
735
 
function append_sid($url, $params = false, $is_amp = true, $session_id = false)
736
 
{
737
 
        global $_SID, $_EXTRA_URL, $phpbb_hook;
738
 
 
739
 
        // Developers using the hook function need to globalise the $_SID and $_EXTRA_URL on their own and also handle it appropiatly.
740
 
        // They could mimick most of what is within this function
741
 
        if ($phpbb_hook-&gt;call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))
742
 
        {
743
 
                if ($phpbb_hook-&gt;hook_return(__FUNCTION__))
744
 
                {
745
 
                        return $phpbb_hook-&gt;hook_return_result(__FUNCTION__);
746
 
                }
747
 
        }
748
 
 
749
 
        [...]
750
 
}
751
 
 
752
 
// The function called
753
 
function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
754
 
{
755
 
        // Get possible previous results
756
 
        $result = $hook-&gt;previous_hook_result('append_sid');
757
 
 
758
 
        [...]
759
 
 
760
 
        // I only rewrite some variables, but return nothing. Therefore, the append_sid() function will not return my (non)result.
761
 
}
762
 
</pre></div>
763
 
 
764
 
<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>
765
 
 
766
 
<div class="codebox"><pre>
767
 
// The function called
768
 
function my_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
769
 
{
770
 
        // Get possible previous results
771
 
        $result = $hook-&gt;previous_hook_result('append_sid');
772
 
 
773
 
        // $result is not filled
774
 
 
775
 
        return 'FILLED';
776
 
}
777
 
 
778
 
// This function is registered too and gets executed after my_append_sid()
779
 
function my_own_append_sid(&amp;$hook, $url, $params = false, $is_amp = true, $session_id = false)
780
 
{
781
 
        $result = $hook->previous_hook_result('append_sid');
782
 
 
783
 
        // $result is actually filled with $result['result'] = 'FILLED'
784
 
        // But i return nothing, therefore append_sid() continues it's execution.
785
 
}
786
 
 
787
 
// The way both functions are registered.
788
 
$phpbb_hook->register('append_sid', 'my_append_sid');
789
 
$phpbb_hook->register('append_sid', 'my_own_append_sid');
790
 
</pre></div>
791
 
 
792
 
                </div>
793
 
 
794
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
795
 
 
796
 
                <span class="corners-bottom"><span></span></span></div>
797
 
        </div>
798
 
 
799
 
        <a name="embed"></a><h2>5. Embedding your hook files/classes/methods</h2>
800
 
 
801
 
        <div class="paragraph">
802
 
                <div class="inner"><span class="corners-top"><span></span></span>
803
 
 
804
 
                <div class="content">
805
 
 
806
 
<p>There are basically two methods you are able to choose from:</p>
807
 
 
808
 
<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>
809
 
 
810
 
<p>Please be aware that you need to purge your cache within the ACP to make your newly placed file available to phpBB3.</p>
811
 
 
812
 
<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>
813
 
 
814
 
<div class="codebox"><pre>
815
 
// My function which gets executed within the hooks constuctor
816
 
function phpbb_hook_register(&amp;$hook)
817
 
{
818
 
        $hook-&gt;register('append_sid', 'my_append_sid');
819
 
}
820
 
 
821
 
[...]
822
 
</pre></div>
823
 
 
824
 
<p>You should get the idea. ;)</p>
825
 
 
826
 
                </div>
827
 
 
828
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
829
 
 
830
 
                <span class="corners-bottom"><span></span></span></div>
831
 
        </div>
832
 
 
833
 
        <a name="disclaimer"></a><h2>6. Copyright and disclaimer</h2>
834
 
 
835
 
        <div class="paragraph">
836
 
                <div class="inner"><span class="corners-top"><span></span></span>
837
 
 
838
 
                <div class="content">
839
 
 
840
 
        <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>
841
 
 
842
 
                </div>
843
 
 
844
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
845
 
 
846
 
                <span class="corners-bottom"><span></span></span></div>
847
 
        </div>
848
 
 
849
 
        <div id="page-footer">
850
 
                <div class="version">$Id: hook_system.html,v 1.4 2007/11/18 15:37:17 naderman Exp $</div>
851
 
        </div>
852
 
</div></div>
853
 
 
854
 
<div>
855
 
        <a id="bottom" name="bottom" accesskey="z"></a>
856
 
</div>
857
 
 
858
 
</body>
859
 
</html>