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

<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->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

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

395

396

397

</div>

398

399

<a name="use"></a><h2>2. Allow hooks in functions/methods</h2>

400

401

402

403

404

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

411

function my_own_function($my_first_parameter, $my_second_parameter)

412

{

413

global $phpbb_hook;

414

415

if ($phpbb_hook->call_hook(__FUNCTION__, $my_first_parameter, $my_second_parameter))

416

{

417

if ($phpbb_hook->hook_return(__FUNCTION__))

418

{

419

return $phpbb_hook->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

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->call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))

439

{

440

if ($phpbb_hook->hook_return(array(__CLASS__, __FUNCTION__)))

441

{

442

return $phpbb_hook->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

456

// Adding your own hookable function:

457

$phpbb_hook->add_hook('my_own_function');

458

459

// Adding your own hookable method:

460

$phpbb_hook->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->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

469

470

471

</div>

472

473

<a name="register"></a><h2>3. Registering hooks</h2>

474

475

476

477

478

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

485

class my_append_sid_class

486

{

487

// Our functions

488

function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)

489

{

490

// Get possible previous results

491

$result = $hook->previous_hook_result('append_sid');

492

493

return $result['result'] . '<br />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(&$hook, $url, $params = false, $is_amp = true, $session_id = false)

501

{

502

// Get possible previous results

503

$result = $hook->previous_hook_result('append_sid');

504

505

echo $result['result'] . '<br />I was called as the third one.';

506

}

507

}

508

509

// And a normal function

510

function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)

511

{

512

// Get possible previous results

513

$result = $hook->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>&$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->register()</code> method:</p>

525

526

527

// Now, we register our append_sid "replacements" in a stacked way...

528

// Registering the function (this is called first)

529

$phpbb_hook->register('append_sid', 'my_append_sid');

530

531

// Registering the first class

532

$phpbb_hook->register('append_sid', array('my_append_sid_class', 'my_append_sid'));

533

$phpbb_hook->register('append_sid', array(&$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

539

// Registering hook, which will be called

540

$phpbb_hook->register('append_sid', 'my_own_append_sid');

541

542

// Add hook to our called hook function

543

$phpbb_hook->add_hook('my_own_append_sid');

544

545

// Register added hook

546

$phpbb_hook->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->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->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->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

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->call_hook)

580

{

581

global $phpbb_hook;

582

583

if ($phpbb_hook->call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))

584

{

585

if ($phpbb_hook->hook_return(array(__CLASS__, __FUNCTION__)))

586

{

587

return $phpbb_hook->hook_return_result(array(__CLASS__, __FUNCTION__));

588

}

589

}

590

}

591

592

return 'not hooked';

593

}

594

}

595

596

function hooking(&$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->add_hook(array('my_hookable_object2', 'hook_me'));

605

606

$phpbb_hook->register(array('my_hookable_object2', 'hook_me'), 'hooking');

607

608

// Do not call the hook for $first_object

609

$first_object->call_hook = false;

610

611

echo $first_object->hook_me('first', 'second') . '<br />';

612

echo $second_object->hook_me('first', 'second') . '<br />';

613

</pre></div>

614

615

<p>OUTPUT:</p>

616

617

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

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->call_hook(array(__CLASS__, __FUNCTION__), $my_first_parameter, $my_second_parameter))

641

{

642

if ($phpbb_hook->hook_return(array(__CLASS__, __FUNCTION__)))

643

{

644

return $phpbb_hook->hook_return_result(array(__CLASS__, __FUNCTION__));

645

}

646

}

647

}

648

649

return 'not hooked';

650

}

651

}

652

653

function hooking(&$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->add_hook(array('my_hookable_object2', 'hook_me'));

662

663

$phpbb_hook->register(array('my_hookable_object2', 'hook_me'), 'hooking');

664

665

echo $first_object->hook_me('first', 'second', false) . '<br />';

666

echo $second_object->hook_me('first', 'second') . '<br />';

667

</pre></div>

668

669

<p>OUTPUT:</p>

670

671

672

not hooked

673

hooked

674

</pre></div>

675

676

</div>

677

678

679

680

681

</div>

682

683

<a name="return"></a><h2>4. Result returning</h2>

684

685

686

687

688

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

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->call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))

704

{

705

if ($phpbb_hook->hook_return(__FUNCTION__))

706

{

707

return $phpbb_hook->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

718

// The function called

719

function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)

720

{

721

// Get possible previous results

722

$result = $hook->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

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->call_hook(__FUNCTION__, $url, $params, $is_amp, $session_id))

742

{

743

if ($phpbb_hook->hook_return(__FUNCTION__))

744

{

745

return $phpbb_hook->hook_return_result(__FUNCTION__);

746

}

747

}

748

749

[...]

750

}

751

752

// The function called

753

function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)

754

{

755

// Get possible previous results

756

$result = $hook->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

767

// The function called

768

function my_append_sid(&$hook, $url, $params = false, $is_amp = true, $session_id = false)

769

{

770

// Get possible previous results

771

$result = $hook->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(&$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

795

796

797

</div>

798

799

<a name="embed"></a><h2>5. Embedding your hook files/classes/methods</h2>

800

801

802

803

804

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

815

// My function which gets executed within the hooks constuctor

816

function phpbb_hook_register(&$hook)

817

{

818

$hook->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

829

830

831

</div>

832

833

<a name="disclaimer"></a><h2>6. Copyright and disclaimer</h2>

834

835

836

837

838

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

845

846

847

</div>

848

849

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

856

</div>

857

858

</body>

859

</html>

Older »