home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 April / PCWorld_2005-04_cd.bin / akce / web / phpmanual / phpmanual.exe / php_manual_en.html.htm < prev    next >
Encoding:
Extensible Markup Language  |  2005-01-13  |  9.8 MB  |  670,325 lines
Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents.
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2. <HTML
  3. ><HEAD
  4. ><TITLE
  5. >PHP Manual</TITLE
  6. ><META
  7. NAME="GENERATOR"
  8. CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><META
  9. HTTP-EQUIV="Content-type"
  10. CONTENT="text/html; charset=ISO-8859-1"></HEAD
  11. ><BODY
  12. CLASS="book"
  13. BGCOLOR="#FFFFFF"
  14. TEXT="#000000"
  15. LINK="#0000FF"
  16. VLINK="#840084"
  17. ALINK="#0000FF"
  18. ><DIV
  19. CLASS="BOOK"
  20. ><A
  21. NAME="manual"
  22. ></A
  23. ><DIV
  24. CLASS="TITLEPAGE"
  25. ><H1
  26. CLASS="title"
  27. ><A
  28. NAME="bookinfo"
  29. >PHP Manual</A
  30. ></H1
  31. ><DIV
  32. CLASS="author"
  33. >Mehdi Achour</DIV
  34. ><DIV
  35. CLASS="author"
  36. >Friedhelm Betz</DIV
  37. ><DIV
  38. CLASS="author"
  39. >Antony Dovgal</DIV
  40. ><DIV
  41. CLASS="author"
  42. >Nuno Lopes</DIV
  43. ><DIV
  44. CLASS="author"
  45. >Philip Olson</DIV
  46. ><DIV
  47. CLASS="author"
  48. >Georg Richter</DIV
  49. ><DIV
  50. CLASS="author"
  51. >Damien Seguy</DIV
  52. ><DIV
  53. CLASS="author"
  54. >Jakub Vrana</DIV
  55. ><SPAN
  56. CLASS="collab"
  57. ><SPAN
  58. CLASS="collabname"
  59. >      <A
  60. HREF="#contributors"
  61. >And several others</A
  62. >
  63.     </SPAN
  64. ><BR></SPAN
  65. ><H2
  66. CLASS="EDITEDBY"
  67. >Edited by</H2
  68. ><DIV
  69. CLASS="editor"
  70. >Gabor Hojtsy</DIV
  71. ><P
  72. CLASS="pubdate"
  73. >03-01-2005<BR></P
  74. ><P
  75. CLASS="copyright"
  76. >Copyright © 1997-2005 the PHP Documentation Group</P
  77. ><DIV
  78. CLASS="legalnotice"
  79. ><A
  80. NAME="copyright"
  81. ></A
  82. ><P
  83. ><B
  84. >Copyright</B
  85. ></P
  86. ><P
  87. >     Copyright ┬⌐ 1997 - 2005 by the PHP Documentation Group.
  88.     This material may be distributed only subject to the terms and
  89.     conditions set forth in the Open Publication License, v1.0 or
  90.     later. A copy of the <A
  91. HREF="#opl.license"
  92. >Open Publication
  93.     License</A
  94. > is distributed with this manual, the latest version
  95.     is presently available at <A
  96. HREF="http://www.opencontent.org/openpub/"
  97. TARGET="_top"
  98. >http://www.opencontent.org/openpub/</A
  99. >.
  100.    </P
  101. ><P
  102. >     Distribution of substantively modified versions of this document
  103.     is prohibited without the explicit permission of the copyright
  104.     holder.
  105.    </P
  106. ><P
  107. >     Distribution of the work or derivative of the work in any
  108.     standard (paper) book form is prohibited unless prior permission
  109.     is obtained from the copyright holder.
  110.    </P
  111. ><P
  112. >     In case you are interested in redistribution or republishing of this document
  113.     in whole or in part, either modified or unmodified, and you have questions,
  114.     please contact the copyright holders at
  115.     <A
  116. HREF="mailto:doc-license@lists.php.net"
  117. TARGET="_top"
  118. >doc-license@lists.php.net</A
  119. >.
  120.     Note that this address is mapped to a publicly archived mailing list.
  121.    </P
  122. ><P
  123. >     The 'Extending PHP 4.0' section of this manual is copyright ┬⌐ 2000 by
  124.     Zend Technologies, Ltd. This material may be distributed only subject to
  125.     the terms and conditions set forth in the Open Publication License, v1.0
  126.     or later (the latest version is presently available at
  127.     <A
  128. HREF="http://www.opencontent.org/openpub/"
  129. TARGET="_top"
  130. >http://www.opencontent.org/openpub/</A
  131. >).
  132.    </P
  133. ></DIV
  134. ><HR></DIV
  135. ><DIV
  136. CLASS="TOC"
  137. ><DL
  138. ><DT
  139. ><B
  140. >Table of Contents</B
  141. ></DT
  142. ><DT
  143. ><A
  144. HREF="#preface"
  145. >Preface</A
  146. ></DT
  147. ><DD
  148. ><DL
  149. ><DT
  150. ><A
  151. HREF="#contributors"
  152. >Authors and Contributors</A
  153. ></DT
  154. ></DL
  155. ></DD
  156. ><DT
  157. >I. <A
  158. HREF="#getting-started"
  159. >Getting Started</A
  160. ></DT
  161. ><DD
  162. ><DL
  163. ><DT
  164. >1. <A
  165. HREF="#introduction"
  166. >Introduction</A
  167. ></DT
  168. ><DT
  169. >2. <A
  170. HREF="#tutorial"
  171. >A simple tutorial</A
  172. ></DT
  173. ></DL
  174. ></DD
  175. ><DT
  176. >II. <A
  177. HREF="#install"
  178. >Installation and Configuration</A
  179. ></DT
  180. ><DD
  181. ><DL
  182. ><DT
  183. >3. <A
  184. HREF="#install.general"
  185. >General Installation Considerations</A
  186. ></DT
  187. ><DT
  188. >4. <A
  189. HREF="#install.unix"
  190. >Installation on Unix systems</A
  191. ></DT
  192. ><DT
  193. >5. <A
  194. HREF="#install.macosx"
  195. >Installation on Mac OS X</A
  196. ></DT
  197. ><DT
  198. >6. <A
  199. HREF="#install.windows"
  200. >Installation on Windows systems</A
  201. ></DT
  202. ><DT
  203. >7. <A
  204. HREF="#install.pecl"
  205. >Installation of PECL extensions</A
  206. ></DT
  207. ><DT
  208. >8. <A
  209. HREF="#install.problems"
  210. >Problems?</A
  211. ></DT
  212. ><DT
  213. >9. <A
  214. HREF="#configuration"
  215. >Runtime Configuration</A
  216. ></DT
  217. ></DL
  218. ></DD
  219. ><DT
  220. >III. <A
  221. HREF="#langref"
  222. >Language Reference</A
  223. ></DT
  224. ><DD
  225. ><DL
  226. ><DT
  227. >10. <A
  228. HREF="#language.basic-syntax"
  229. >Basic syntax</A
  230. ></DT
  231. ><DT
  232. >11. <A
  233. HREF="#language.types"
  234. >Types</A
  235. ></DT
  236. ><DT
  237. >12. <A
  238. HREF="#language.variables"
  239. >Variables</A
  240. ></DT
  241. ><DT
  242. >13. <A
  243. HREF="#language.constants"
  244. >Constants</A
  245. ></DT
  246. ><DT
  247. >14. <A
  248. HREF="#language.expressions"
  249. >Expressions</A
  250. ></DT
  251. ><DT
  252. >15. <A
  253. HREF="#language.operators"
  254. >Operators</A
  255. ></DT
  256. ><DT
  257. >16. <A
  258. HREF="#language.control-structures"
  259. >Control Structures</A
  260. ></DT
  261. ><DT
  262. >17. <A
  263. HREF="#language.functions"
  264. >Functions</A
  265. ></DT
  266. ><DT
  267. >18. <A
  268. HREF="#language.oop"
  269. >Classes and Objects (PHP 4)</A
  270. ></DT
  271. ><DT
  272. >19. <A
  273. HREF="#language.oop5"
  274. >Classes and Objects (PHP 5)</A
  275. ></DT
  276. ><DT
  277. >20. <A
  278. HREF="#language.exceptions"
  279. >Exceptions</A
  280. ></DT
  281. ><DT
  282. >21. <A
  283. HREF="#language.references"
  284. >References Explained</A
  285. ></DT
  286. ></DL
  287. ></DD
  288. ><DT
  289. >IV. <A
  290. HREF="#security"
  291. >Security</A
  292. ></DT
  293. ><DD
  294. ><DL
  295. ><DT
  296. >22. <A
  297. HREF="#security.intro"
  298. >Introduction</A
  299. ></DT
  300. ><DT
  301. >23. <A
  302. HREF="#security.general"
  303. >General considerations</A
  304. ></DT
  305. ><DT
  306. >24. <A
  307. HREF="#security.cgi-bin"
  308. >Installed as CGI binary</A
  309. ></DT
  310. ><DT
  311. >25. <A
  312. HREF="#security.apache"
  313. >Installed as an Apache module</A
  314. ></DT
  315. ><DT
  316. >26. <A
  317. HREF="#security.filesystem"
  318. >Filesystem Security</A
  319. ></DT
  320. ><DT
  321. >27. <A
  322. HREF="#security.database"
  323. >Database Security</A
  324. ></DT
  325. ><DT
  326. >28. <A
  327. HREF="#security.errors"
  328. >Error Reporting</A
  329. ></DT
  330. ><DT
  331. >29. <A
  332. HREF="#security.globals"
  333. >Using Register Globals</A
  334. ></DT
  335. ><DT
  336. >30. <A
  337. HREF="#security.variables"
  338. >User Submitted Data</A
  339. ></DT
  340. ><DT
  341. >31. <A
  342. HREF="#security.magicquotes"
  343. >Magic Quotes</A
  344. ></DT
  345. ><DT
  346. >32. <A
  347. HREF="#security.hiding"
  348. >Hiding PHP</A
  349. ></DT
  350. ><DT
  351. >33. <A
  352. HREF="#security.current"
  353. >Keeping Current</A
  354. ></DT
  355. ></DL
  356. ></DD
  357. ><DT
  358. >V. <A
  359. HREF="#features"
  360. >Features</A
  361. ></DT
  362. ><DD
  363. ><DL
  364. ><DT
  365. >34. <A
  366. HREF="#features.http-auth"
  367. >HTTP authentication with PHP</A
  368. ></DT
  369. ><DT
  370. >35. <A
  371. HREF="#features.cookies"
  372. >Cookies</A
  373. ></DT
  374. ><DT
  375. >36. <A
  376. HREF="#features.sessions"
  377. >Sessions</A
  378. ></DT
  379. ><DT
  380. >37. <A
  381. HREF="#features.xforms"
  382. >Dealing with XForms</A
  383. ></DT
  384. ><DT
  385. >38. <A
  386. HREF="#features.file-upload"
  387. >Handling file uploads</A
  388. ></DT
  389. ><DT
  390. >39. <A
  391. HREF="#features.remote-files"
  392. >Using remote files</A
  393. ></DT
  394. ><DT
  395. >40. <A
  396. HREF="#features.connection-handling"
  397. >Connection handling</A
  398. ></DT
  399. ><DT
  400. >41. <A
  401. HREF="#features.persistent-connections"
  402. >Persistent Database Connections</A
  403. ></DT
  404. ><DT
  405. >42. <A
  406. HREF="#features.safe-mode"
  407. >Safe Mode</A
  408. ></DT
  409. ><DT
  410. >43. <A
  411. HREF="#features.commandline"
  412. >Using PHP from the command line</A
  413. ></DT
  414. ></DL
  415. ></DD
  416. ><DT
  417. >VI. <A
  418. HREF="#funcref"
  419. >Function Reference</A
  420. ></DT
  421. ><DD
  422. ><DL
  423. ><DT
  424. >I. <A
  425. HREF="#ref.apache"
  426. >Apache-specific Functions</A
  427. ></DT
  428. ><DT
  429. >II. <A
  430. HREF="#ref.apd"
  431. >Advanced PHP debugger</A
  432. ></DT
  433. ><DT
  434. >III. <A
  435. HREF="#ref.array"
  436. >Array Functions</A
  437. ></DT
  438. ><DT
  439. >IV. <A
  440. HREF="#ref.aspell"
  441. >Aspell functions [deprecated]</A
  442. ></DT
  443. ><DT
  444. >V. <A
  445. HREF="#ref.bc"
  446. >BCMath Arbitrary Precision Mathematics Functions</A
  447. ></DT
  448. ><DT
  449. >VI. <A
  450. HREF="#ref.bcompiler"
  451. >PHP bytecode Compiler</A
  452. ></DT
  453. ><DT
  454. >VII. <A
  455. HREF="#ref.bzip2"
  456. >Bzip2 Compression Functions</A
  457. ></DT
  458. ><DT
  459. >VIII. <A
  460. HREF="#ref.calendar"
  461. >Calendar Functions</A
  462. ></DT
  463. ><DT
  464. >IX. <A
  465. HREF="#ref.ccvs"
  466. >CCVS API Functions [deprecated]</A
  467. ></DT
  468. ><DT
  469. >X. <A
  470. HREF="#ref.com"
  471. >COM and .Net (Windows)</A
  472. ></DT
  473. ><DT
  474. >XI. <A
  475. HREF="#ref.classkit"
  476. >Classkit Functions</A
  477. ></DT
  478. ><DT
  479. >XII. <A
  480. HREF="#ref.classobj"
  481. >Class/Object Functions</A
  482. ></DT
  483. ><DT
  484. >XIII. <A
  485. HREF="#ref.cpdf"
  486. >ClibPDF Functions</A
  487. ></DT
  488. ><DT
  489. >XIV. <A
  490. HREF="#ref.crack"
  491. >Crack Functions</A
  492. ></DT
  493. ><DT
  494. >XV. <A
  495. HREF="#ref.curl"
  496. >CURL, Client URL Library Functions</A
  497. ></DT
  498. ><DT
  499. >XVI. <A
  500. HREF="#ref.cybercash"
  501. >Cybercash Payment Functions</A
  502. ></DT
  503. ><DT
  504. >XVII. <A
  505. HREF="#ref.cyrus"
  506. >Cyrus IMAP administration Functions</A
  507. ></DT
  508. ><DT
  509. >XVIII. <A
  510. HREF="#ref.ctype"
  511. >Character Type Functions</A
  512. ></DT
  513. ><DT
  514. >XIX. <A
  515. HREF="#ref.dba"
  516. >Database (dbm-style) Abstraction Layer Functions</A
  517. ></DT
  518. ><DT
  519. >XX. <A
  520. HREF="#ref.datetime"
  521. >Date and Time Functions</A
  522. ></DT
  523. ><DT
  524. >XXI. <A
  525. HREF="#ref.dbase"
  526. >dBase Functions</A
  527. ></DT
  528. ><DT
  529. >XXII. <A
  530. HREF="#ref.dbm"
  531. >DBM Functions [deprecated]</A
  532. ></DT
  533. ><DT
  534. >XXIII. <A
  535. HREF="#ref.dbx"
  536. >dbx Functions</A
  537. ></DT
  538. ><DT
  539. >XXIV. <A
  540. HREF="#ref.dbplus"
  541. >DB++ Functions</A
  542. ></DT
  543. ><DT
  544. >XXV. <A
  545. HREF="#ref.dio"
  546. >Direct IO Functions</A
  547. ></DT
  548. ><DT
  549. >XXVI. <A
  550. HREF="#ref.dir"
  551. >Directory Functions</A
  552. ></DT
  553. ><DT
  554. >XXVII. <A
  555. HREF="#ref.dom"
  556. >DOM Functions</A
  557. ></DT
  558. ><DT
  559. >XXVIII. <A
  560. HREF="#ref.domxml"
  561. >DOM XML Functions</A
  562. ></DT
  563. ><DT
  564. >XXIX. <A
  565. HREF="#ref.dotnet"
  566. >.NET Functions</A
  567. ></DT
  568. ><DT
  569. >XXX. <A
  570. HREF="#ref.errorfunc"
  571. >Error Handling and Logging Functions</A
  572. ></DT
  573. ><DT
  574. >XXXI. <A
  575. HREF="#ref.exif"
  576. >Exif Functions</A
  577. ></DT
  578. ><DT
  579. >XXXII. <A
  580. HREF="#ref.fam"
  581. >File Alteration Monitor Functions</A
  582. ></DT
  583. ><DT
  584. >XXXIII. <A
  585. HREF="#ref.fbsql"
  586. >FrontBase Functions</A
  587. ></DT
  588. ><DT
  589. >XXXIV. <A
  590. HREF="#ref.filepro"
  591. >filePro Functions</A
  592. ></DT
  593. ><DT
  594. >XXXV. <A
  595. HREF="#ref.filesystem"
  596. >Filesystem Functions</A
  597. ></DT
  598. ><DT
  599. >XXXVI. <A
  600. HREF="#ref.fdf"
  601. >Forms Data Format Functions</A
  602. ></DT
  603. ><DT
  604. >XXXVII. <A
  605. HREF="#ref.fribidi"
  606. >FriBiDi Functions</A
  607. ></DT
  608. ><DT
  609. >XXXVIII. <A
  610. HREF="#ref.ftp"
  611. >FTP Functions</A
  612. ></DT
  613. ><DT
  614. >XXXIX. <A
  615. HREF="#ref.funchand"
  616. >Function Handling Functions</A
  617. ></DT
  618. ><DT
  619. >XL. <A
  620. HREF="#ref.gettext"
  621. >Gettext</A
  622. ></DT
  623. ><DT
  624. >XLI. <A
  625. HREF="#ref.gmp"
  626. >GMP Functions</A
  627. ></DT
  628. ><DT
  629. >XLII. <A
  630. HREF="#ref.http"
  631. >HTTP Functions</A
  632. ></DT
  633. ><DT
  634. >XLIII. <A
  635. HREF="#ref.hw"
  636. >Hyperwave Functions</A
  637. ></DT
  638. ><DT
  639. >XLIV. <A
  640. HREF="#ref.hwapi"
  641. >Hyperwave API Functions</A
  642. ></DT
  643. ><DT
  644. >XLV. <A
  645. HREF="#ref.iconv"
  646. >iconv Functions</A
  647. ></DT
  648. ><DT
  649. >XLVI. <A
  650. HREF="#ref.image"
  651. >Image Functions</A
  652. ></DT
  653. ><DT
  654. >XLVII. <A
  655. HREF="#ref.imap"
  656. >IMAP, POP3 and NNTP Functions</A
  657. ></DT
  658. ><DT
  659. >XLVIII. <A
  660. HREF="#ref.ifx"
  661. >Informix Functions</A
  662. ></DT
  663. ><DT
  664. >XLIX. <A
  665. HREF="#ref.ibase"
  666. >Firebird/InterBase Functions</A
  667. ></DT
  668. ><DT
  669. >L. <A
  670. HREF="#ref.id3"
  671. >ID3 Functions</A
  672. ></DT
  673. ><DT
  674. >LI. <A
  675. HREF="#ref.ingres"
  676. >Ingres II Functions</A
  677. ></DT
  678. ><DT
  679. >LII. <A
  680. HREF="#ref.ircg"
  681. >IRC Gateway Functions</A
  682. ></DT
  683. ><DT
  684. >LIII. <A
  685. HREF="#ref.java"
  686. >PHP / Java Integration</A
  687. ></DT
  688. ><DT
  689. >LIV. <A
  690. HREF="#ref.ldap"
  691. >LDAP Functions</A
  692. ></DT
  693. ><DT
  694. >LV. <A
  695. HREF="#ref.lzf"
  696. >LZF Functions</A
  697. ></DT
  698. ><DT
  699. >LVI. <A
  700. HREF="#ref.mail"
  701. >Mail Functions</A
  702. ></DT
  703. ><DT
  704. >LVII. <A
  705. HREF="#ref.mailparse"
  706. >mailparse Functions</A
  707. ></DT
  708. ><DT
  709. >LVIII. <A
  710. HREF="#ref.math"
  711. >Mathematical Functions</A
  712. ></DT
  713. ><DT
  714. >LIX. <A
  715. HREF="#ref.mbstring"
  716. >Multibyte String Functions</A
  717. ></DT
  718. ><DT
  719. >LX. <A
  720. HREF="#ref.mcal"
  721. >MCAL Functions</A
  722. ></DT
  723. ><DT
  724. >LXI. <A
  725. HREF="#ref.mcrypt"
  726. >Mcrypt Encryption Functions</A
  727. ></DT
  728. ><DT
  729. >LXII. <A
  730. HREF="#ref.mcve"
  731. >MCVE Payment Functions</A
  732. ></DT
  733. ><DT
  734. >LXIII. <A
  735. HREF="#ref.memcache"
  736. >Memcache Functions</A
  737. ></DT
  738. ><DT
  739. >LXIV. <A
  740. HREF="#ref.mhash"
  741. >Mhash Functions</A
  742. ></DT
  743. ><DT
  744. >LXV. <A
  745. HREF="#ref.mime-magic"
  746. >Mimetype Functions</A
  747. ></DT
  748. ><DT
  749. >LXVI. <A
  750. HREF="#ref.mssql"
  751. >Microsoft SQL Server Functions</A
  752. ></DT
  753. ><DT
  754. >LXVII. <A
  755. HREF="#ref.ming"
  756. >Ming functions for Flash</A
  757. ></DT
  758. ><DT
  759. >LXVIII. <A
  760. HREF="#ref.misc"
  761. >Miscellaneous Functions</A
  762. ></DT
  763. ><DT
  764. >LXIX. <A
  765. HREF="#ref.mnogosearch"
  766. >mnoGoSearch Functions</A
  767. ></DT
  768. ><DT
  769. >LXX. <A
  770. HREF="#ref.msql"
  771. >mSQL Functions</A
  772. ></DT
  773. ><DT
  774. >LXXI. <A
  775. HREF="#ref.mysql"
  776. >MySQL Functions</A
  777. ></DT
  778. ><DT
  779. >LXXII. <A
  780. HREF="#ref.mysqli"
  781. >Improved MySQL Extension</A
  782. ></DT
  783. ><DT
  784. >LXXIII. <A
  785. HREF="#ref.msession"
  786. >Mohawk Software Session Handler Functions</A
  787. ></DT
  788. ><DT
  789. >LXXIV. <A
  790. HREF="#ref.muscat"
  791. >muscat Functions</A
  792. ></DT
  793. ><DT
  794. >LXXV. <A
  795. HREF="#ref.network"
  796. >Network Functions</A
  797. ></DT
  798. ><DT
  799. >LXXVI. <A
  800. HREF="#ref.ncurses"
  801. >Ncurses Terminal Screen Control Functions</A
  802. ></DT
  803. ><DT
  804. >LXXVII. <A
  805. HREF="#ref.notes"
  806. >Lotus Notes Functions</A
  807. ></DT
  808. ><DT
  809. >LXXVIII. <A
  810. HREF="#ref.nsapi"
  811. >NSAPI-specific Functions</A
  812. ></DT
  813. ><DT
  814. >LXXIX. <A
  815. HREF="#ref.uodbc"
  816. >ODBC Functions (Unified)</A
  817. ></DT
  818. ><DT
  819. >LXXX. <A
  820. HREF="#ref.objaggregation"
  821. >Object Aggregation/Composition Functions</A
  822. ></DT
  823. ><DT
  824. >LXXXI. <A
  825. HREF="#ref.oci8"
  826. >Oracle 8 functions</A
  827. ></DT
  828. ><DT
  829. >LXXXII. <A
  830. HREF="#ref.openal"
  831. >OpenAL Audio Bindings</A
  832. ></DT
  833. ><DT
  834. >LXXXIII. <A
  835. HREF="#ref.openssl"
  836. >OpenSSL Functions</A
  837. ></DT
  838. ><DT
  839. >LXXXIV. <A
  840. HREF="#ref.oracle"
  841. >Oracle Functions</A
  842. ></DT
  843. ><DT
  844. >LXXXV. <A
  845. HREF="#ref.ovrimos"
  846. >Ovrimos SQL Functions</A
  847. ></DT
  848. ><DT
  849. >LXXXVI. <A
  850. HREF="#ref.outcontrol"
  851. >Output Control Functions</A
  852. ></DT
  853. ><DT
  854. >LXXXVII. <A
  855. HREF="#ref.overload"
  856. >Object property and method call overloading</A
  857. ></DT
  858. ><DT
  859. >LXXXVIII. <A
  860. HREF="#ref.parsekit"
  861. >Parsekit Functions</A
  862. ></DT
  863. ><DT
  864. >LXXXIX. <A
  865. HREF="#ref.pdf"
  866. >PDF functions</A
  867. ></DT
  868. ><DT
  869. >XC. <A
  870. HREF="#ref.pdo"
  871. >PDO Functions</A
  872. ></DT
  873. ><DT
  874. >XCI. <A
  875. HREF="#ref.pfpro"
  876. >Verisign Payflow Pro Functions</A
  877. ></DT
  878. ><DT
  879. >XCII. <A
  880. HREF="#ref.info"
  881. >PHP Options&Information</A
  882. ></DT
  883. ><DT
  884. >XCIII. <A
  885. HREF="#ref.posix"
  886. >POSIX Functions</A
  887. ></DT
  888. ><DT
  889. >XCIV. <A
  890. HREF="#ref.pgsql"
  891. >PostgreSQL Functions</A
  892. ></DT
  893. ><DT
  894. >XCV. <A
  895. HREF="#ref.pcntl"
  896. >Process Control Functions</A
  897. ></DT
  898. ><DT
  899. >XCVI. <A
  900. HREF="#ref.exec"
  901. >Program Execution Functions</A
  902. ></DT
  903. ><DT
  904. >XCVII. <A
  905. HREF="#ref.printer"
  906. >Printer Functions</A
  907. ></DT
  908. ><DT
  909. >XCVIII. <A
  910. HREF="#ref.pspell"
  911. >Pspell Functions</A
  912. ></DT
  913. ><DT
  914. >XCIX. <A
  915. HREF="#ref.readline"
  916. >GNU Readline</A
  917. ></DT
  918. ><DT
  919. >C. <A
  920. HREF="#ref.recode"
  921. >GNU Recode Functions</A
  922. ></DT
  923. ><DT
  924. >CI. <A
  925. HREF="#ref.pcre"
  926. >Regular Expression Functions (Perl-Compatible)</A
  927. ></DT
  928. ><DT
  929. >CII. <A
  930. HREF="#ref.qtdom"
  931. >qtdom Functions</A
  932. ></DT
  933. ><DT
  934. >CIII. <A
  935. HREF="#ref.rar"
  936. >Rar Functions</A
  937. ></DT
  938. ><DT
  939. >CIV. <A
  940. HREF="#ref.regex"
  941. >Regular Expression Functions (POSIX Extended)</A
  942. ></DT
  943. ><DT
  944. >CV. <A
  945. HREF="#ref.ssh2"
  946. >Secure Shell2 Functions</A
  947. ></DT
  948. ><DT
  949. >CVI. <A
  950. HREF="#ref.sem"
  951. >Semaphore, Shared Memory and IPC Functions</A
  952. ></DT
  953. ><DT
  954. >CVII. <A
  955. HREF="#ref.sesam"
  956. >SESAM Database Functions</A
  957. ></DT
  958. ><DT
  959. >CVIII. <A
  960. HREF="#ref.session"
  961. >Session Handling Functions</A
  962. ></DT
  963. ><DT
  964. >CIX. <A
  965. HREF="#ref.shmop"
  966. >Shared Memory Functions</A
  967. ></DT
  968. ><DT
  969. >CX. <A
  970. HREF="#ref.simplexml"
  971. >SimpleXML functions</A
  972. ></DT
  973. ><DT
  974. >CXI. <A
  975. HREF="#ref.soap"
  976. >SOAP Functions</A
  977. ></DT
  978. ><DT
  979. >CXII. <A
  980. HREF="#ref.sqlite"
  981. >SQLite</A
  982. ></DT
  983. ><DT
  984. >CXIII. <A
  985. HREF="#ref.swf"
  986. >Shockwave Flash Functions</A
  987. ></DT
  988. ><DT
  989. >CXIV. <A
  990. HREF="#ref.snmp"
  991. >SNMP Functions</A
  992. ></DT
  993. ><DT
  994. >CXV. <A
  995. HREF="#ref.sockets"
  996. >Socket Functions</A
  997. ></DT
  998. ><DT
  999. >CXVI. <A
  1000. HREF="#ref.spl"
  1001. >Standard PHP Library (SPL) Functions</A
  1002. ></DT
  1003. ><DT
  1004. >CXVII. <A
  1005. HREF="#ref.stream"
  1006. >Stream Functions</A
  1007. ></DT
  1008. ><DT
  1009. >CXVIII. <A
  1010. HREF="#ref.strings"
  1011. >String Functions</A
  1012. ></DT
  1013. ><DT
  1014. >CXIX. <A
  1015. HREF="#ref.sybase"
  1016. >Sybase Functions</A
  1017. ></DT
  1018. ><DT
  1019. >CXX. <A
  1020. HREF="#ref.tcpwrap"
  1021. >TCP Wrappers Functions</A
  1022. ></DT
  1023. ><DT
  1024. >CXXI. <A
  1025. HREF="#ref.tidy"
  1026. >Tidy Functions</A
  1027. ></DT
  1028. ><DT
  1029. >CXXII. <A
  1030. HREF="#ref.tokenizer"
  1031. >Tokenizer Functions</A
  1032. ></DT
  1033. ><DT
  1034. >CXXIII. <A
  1035. HREF="#ref.url"
  1036. >URL Functions</A
  1037. ></DT
  1038. ><DT
  1039. >CXXIV. <A
  1040. HREF="#ref.var"
  1041. >Variable Functions</A
  1042. ></DT
  1043. ><DT
  1044. >CXXV. <A
  1045. HREF="#ref.vpopmail"
  1046. >vpopmail Functions</A
  1047. ></DT
  1048. ><DT
  1049. >CXXVI. <A
  1050. HREF="#ref.w32api"
  1051. >W32api Functions</A
  1052. ></DT
  1053. ><DT
  1054. >CXXVII. <A
  1055. HREF="#ref.wddx"
  1056. >WDDX Functions</A
  1057. ></DT
  1058. ><DT
  1059. >CXXVIII. <A
  1060. HREF="#ref.xattr"
  1061. >xattr Functions</A
  1062. ></DT
  1063. ><DT
  1064. >CXXIX. <A
  1065. HREF="#ref.xml"
  1066. >XML Parser Functions</A
  1067. ></DT
  1068. ><DT
  1069. >CXXX. <A
  1070. HREF="#ref.xmlrpc"
  1071. >XML-RPC Functions</A
  1072. ></DT
  1073. ><DT
  1074. >CXXXI. <A
  1075. HREF="#ref.xdiff"
  1076. >xdiff Functions</A
  1077. ></DT
  1078. ><DT
  1079. >CXXXII. <A
  1080. HREF="#ref.xsl"
  1081. >XSL functions</A
  1082. ></DT
  1083. ><DT
  1084. >CXXXIII. <A
  1085. HREF="#ref.xslt"
  1086. >XSLT Functions</A
  1087. ></DT
  1088. ><DT
  1089. >CXXXIV. <A
  1090. HREF="#ref.yaz"
  1091. >YAZ Functions</A
  1092. ></DT
  1093. ><DT
  1094. >CXXXV. <A
  1095. HREF="#ref.nis"
  1096. >YP/NIS Functions</A
  1097. ></DT
  1098. ><DT
  1099. >CXXXVI. <A
  1100. HREF="#ref.zip"
  1101. >Zip File Functions (Read Only Access)</A
  1102. ></DT
  1103. ><DT
  1104. >CXXXVII. <A
  1105. HREF="#ref.zlib"
  1106. >Zlib Compression Functions</A
  1107. ></DT
  1108. ></DL
  1109. ></DD
  1110. ><DT
  1111. >VII. <A
  1112. HREF="#zend"
  1113. >Zend API</A
  1114. ></DT
  1115. ><DD
  1116. ><DL
  1117. ><DT
  1118. >44. <A
  1119. HREF="#zend.overview"
  1120. >Overview</A
  1121. ></DT
  1122. ><DT
  1123. >45. <A
  1124. HREF="#zend.possibilities"
  1125. >Extension Possibilities</A
  1126. ></DT
  1127. ><DT
  1128. >46. <A
  1129. HREF="#zend.layout"
  1130. >Source Layout</A
  1131. ></DT
  1132. ><DT
  1133. >47. <A
  1134. HREF="#zend.build"
  1135. >PHP's Automatic Build System</A
  1136. ></DT
  1137. ><DT
  1138. >48. <A
  1139. HREF="#zend.creating"
  1140. >Creating Extensions</A
  1141. ></DT
  1142. ><DT
  1143. >49. <A
  1144. HREF="#zend.using"
  1145. >Using Extensions</A
  1146. ></DT
  1147. ><DT
  1148. >50. <A
  1149. HREF="#zend.troubleshooting"
  1150. >Troubleshooting</A
  1151. ></DT
  1152. ><DT
  1153. >51. <A
  1154. HREF="#zend.structure"
  1155. >Source Discussion</A
  1156. ></DT
  1157. ><DT
  1158. >52. <A
  1159. HREF="#zend.arguments"
  1160. >Accepting Arguments</A
  1161. ></DT
  1162. ><DT
  1163. >53. <A
  1164. HREF="#zend.variables"
  1165. >Creating Variables</A
  1166. ></DT
  1167. ><DT
  1168. >54. <A
  1169. HREF="#zend.copy-constructor"
  1170. >Duplicating Variable Contents: The Copy Constructor</A
  1171. ></DT
  1172. ><DT
  1173. >55. <A
  1174. HREF="#zend.returning"
  1175. >Returning Values</A
  1176. ></DT
  1177. ><DT
  1178. >56. <A
  1179. HREF="#zend.printing"
  1180. >Printing Information</A
  1181. ></DT
  1182. ><DT
  1183. >57. <A
  1184. HREF="#zend.startup-and-shutdown"
  1185. >Startup and Shutdown Functions</A
  1186. ></DT
  1187. ><DT
  1188. >58. <A
  1189. HREF="#zend.calling-user-functions"
  1190. >Calling User Functions</A
  1191. ></DT
  1192. ><DT
  1193. >59. <A
  1194. HREF="#zend.ini-file-support"
  1195. >Initialization File Support</A
  1196. ></DT
  1197. ><DT
  1198. >60. <A
  1199. HREF="#zend.where-to-go"
  1200. >Where to Go from Here</A
  1201. ></DT
  1202. ><DT
  1203. >61. <A
  1204. HREF="#zend.configuration-macros"
  1205. >Reference: Some Configuration Macros</A
  1206. ></DT
  1207. ><DT
  1208. >62. <A
  1209. HREF="#zend.api-macros"
  1210. >API Macros</A
  1211. ></DT
  1212. ></DL
  1213. ></DD
  1214. ><DT
  1215. >VIII. <A
  1216. HREF="#api"
  1217. >PHP API: Interfaces for extension writers</A
  1218. ></DT
  1219. ><DD
  1220. ><DL
  1221. ><DT
  1222. >63. <A
  1223. HREF="#streams"
  1224. >Streams API for PHP Extension Authors</A
  1225. ></DT
  1226. ></DL
  1227. ></DD
  1228. ><DT
  1229. >IX. <A
  1230. HREF="#faq"
  1231. >FAQ: Frequently Asked Questions</A
  1232. ></DT
  1233. ><DD
  1234. ><DL
  1235. ><DT
  1236. >64. <A
  1237. HREF="#faq.general"
  1238. >General Information</A
  1239. ></DT
  1240. ><DT
  1241. >65. <A
  1242. HREF="#faq.mailinglist"
  1243. >Mailing lists</A
  1244. ></DT
  1245. ><DT
  1246. >66. <A
  1247. HREF="#faq.obtaining"
  1248. >Obtaining PHP</A
  1249. ></DT
  1250. ><DT
  1251. >67. <A
  1252. HREF="#faq.databases"
  1253. >Database issues</A
  1254. ></DT
  1255. ><DT
  1256. >68. <A
  1257. HREF="#faq.installation"
  1258. >Installation</A
  1259. ></DT
  1260. ><DT
  1261. >69. <A
  1262. HREF="#faq.build"
  1263. >Build Problems</A
  1264. ></DT
  1265. ><DT
  1266. >70. <A
  1267. HREF="#faq.using"
  1268. >Using PHP</A
  1269. ></DT
  1270. ><DT
  1271. >71. <A
  1272. HREF="#faq.html"
  1273. >PHP and HTML</A
  1274. ></DT
  1275. ><DT
  1276. >72. <A
  1277. HREF="#faq.com"
  1278. >PHP and COM</A
  1279. ></DT
  1280. ><DT
  1281. >73. <A
  1282. HREF="#faq.languages"
  1283. >PHP and other languages</A
  1284. ></DT
  1285. ><DT
  1286. >74. <A
  1287. HREF="#faq.migration"
  1288. >Migrating from PHP 2 to PHP 3</A
  1289. ></DT
  1290. ><DT
  1291. >75. <A
  1292. HREF="#faq.migration4"
  1293. >Migrating from PHP 3 to PHP 4</A
  1294. ></DT
  1295. ><DT
  1296. >76. <A
  1297. HREF="#faq.migration5"
  1298. >Migrating from PHP 4 to PHP 5</A
  1299. ></DT
  1300. ><DT
  1301. >77. <A
  1302. HREF="#faq.misc"
  1303. >Miscellaneous Questions</A
  1304. ></DT
  1305. ></DL
  1306. ></DD
  1307. ><DT
  1308. >X. <A
  1309. HREF="#appendixes"
  1310. >Appendixes</A
  1311. ></DT
  1312. ><DD
  1313. ><DL
  1314. ><DT
  1315. >A. <A
  1316. HREF="#history"
  1317. >History of PHP and related projects</A
  1318. ></DT
  1319. ><DT
  1320. >B. <A
  1321. HREF="#migration5"
  1322. >Migrating from PHP 4 to PHP 5</A
  1323. ></DT
  1324. ><DT
  1325. >C. <A
  1326. HREF="#migration4"
  1327. >Migrating from PHP 3 to PHP 4</A
  1328. ></DT
  1329. ><DT
  1330. >D. <A
  1331. HREF="#migration"
  1332. >Migrating from PHP/FI 2 to PHP 3</A
  1333. ></DT
  1334. ><DT
  1335. >E. <A
  1336. HREF="#debugger"
  1337. >Debugging PHP</A
  1338. ></DT
  1339. ><DT
  1340. >F. <A
  1341. HREF="#phpdevel"
  1342. >Extending PHP 3</A
  1343. ></DT
  1344. ><DT
  1345. >G. <A
  1346. HREF="#configure"
  1347. >Configure options</A
  1348. ></DT
  1349. ><DT
  1350. >H. <A
  1351. HREF="#ini"
  1352. >List of core <TT
  1353. CLASS="filename"
  1354. >php.ini</TT
  1355. > directives</A
  1356. ></DT
  1357. ><DT
  1358. >I. <A
  1359. HREF="#aliases"
  1360. >List of Function Aliases</A
  1361. ></DT
  1362. ><DT
  1363. >J. <A
  1364. HREF="#reserved"
  1365. >List of Reserved Words</A
  1366. ></DT
  1367. ><DT
  1368. >K. <A
  1369. HREF="#resource"
  1370. >List of Resource Types</A
  1371. ></DT
  1372. ><DT
  1373. >L. <A
  1374. HREF="#wrappers"
  1375. >List of Supported Protocols/Wrappers</A
  1376. ></DT
  1377. ><DT
  1378. >M. <A
  1379. HREF="#filters"
  1380. >List of Available Filters</A
  1381. ></DT
  1382. ><DT
  1383. >N. <A
  1384. HREF="#transports"
  1385. >List of Supported Socket Transports</A
  1386. ></DT
  1387. ><DT
  1388. >O. <A
  1389. HREF="#types.comparisons"
  1390. >PHP type comparison tables</A
  1391. ></DT
  1392. ><DT
  1393. >P. <A
  1394. HREF="#tokens"
  1395. >List of Parser Tokens</A
  1396. ></DT
  1397. ><DT
  1398. >Q. <A
  1399. HREF="#about"
  1400. >About the manual</A
  1401. ></DT
  1402. ><DT
  1403. >R. <A
  1404. HREF="#opl.license"
  1405. >Open Publication License</A
  1406. ></DT
  1407. ><DT
  1408. >S. <A
  1409. HREF="#indexes"
  1410. >Function Index</A
  1411. ></DT
  1412. ><DT
  1413. >T. <A
  1414. HREF="#missing-stuff"
  1415. >Missing Stuff</A
  1416. ></DT
  1417. ></DL
  1418. ></DD
  1419. ></DL
  1420. ></DIV
  1421. ><DIV
  1422. CLASS="preface"
  1423. ><HR><H1
  1424. ><A
  1425. NAME="preface"
  1426. >Preface</A
  1427. ></H1
  1428. ><BLOCKQUOTE
  1429. CLASS="ABSTRACT"
  1430. ><DIV
  1431. CLASS="abstract"
  1432. ><P
  1433. ></P
  1434. ><A
  1435. NAME="AEN54"
  1436. ></A
  1437. ><P
  1438. >     <ACRONYM
  1439. CLASS="acronym"
  1440. >PHP</ACRONYM
  1441. >, which stands for "PHP: Hypertext
  1442.     Preprocessor" is a widely-used Open Source general-purpose
  1443.     scripting language that is especially suited for Web
  1444.     development and can be embedded into HTML. Its syntax draws
  1445.     upon C, Java, and Perl, and is easy to learn. The main goal of
  1446.     the language is to allow web developers to write dynamically
  1447.     generated webpages quickly, but you can do much more with PHP.
  1448.    </P
  1449. ><P
  1450. ></P
  1451. ></DIV
  1452. ></BLOCKQUOTE
  1453. ><P
  1454. >    This manual consists primarily of a <A
  1455. HREF="#funcref"
  1456. >    function reference</A
  1457. >, but also contains a 
  1458.    <A
  1459. HREF="#langref"
  1460. >language reference</A
  1461. >, explanations
  1462.    of some of PHP's major <A
  1463. HREF="#features"
  1464. >features</A
  1465. >, 
  1466.    and other <A
  1467. HREF="#appendixes"
  1468. >supplemental</A
  1469. > 
  1470.    information.
  1471.   </P
  1472. ><P
  1473. >    You can download this manual in several formats at <A
  1474. HREF="http://www.php.net/download-docs.php"
  1475. TARGET="_top"
  1476. >http://www.php.net/download-docs.php</A
  1477. >.
  1478.    More information about how this manual is developed can be found in the
  1479.    <A
  1480. HREF="#about"
  1481. >'About the manual'</A
  1482. > appendix. If you are
  1483.    interested in the <A
  1484. HREF="#history"
  1485. >history of PHP</A
  1486. >,
  1487.    visit the relevant appendix.
  1488.   </P
  1489. ><DIV
  1490. CLASS="sect1"
  1491. ><HR><H2
  1492. CLASS="sect1"
  1493. ><A
  1494. NAME="contributors"
  1495. >Authors and Contributors</A
  1496. ></H2
  1497. ><P
  1498. > We highlight the currently most active
  1499. people on the manual frontpage, but there are many more contributors who
  1500. currently help in our work or provided a great amount of help to the project
  1501. in the past. There are a lot of unnamed people who help out with their user
  1502. notes on manual pages, which continually get included in the references, the
  1503. work of whom we are also very thankful for. All the lists provided below are in
  1504. alphabetical order.
  1505. </P
  1506. ><DIV
  1507. CLASS="sect2"
  1508. ><HR><H3
  1509. CLASS="sect2"
  1510. ><A
  1511. NAME="AEN69"
  1512. >Authors and Editors</A
  1513. ></H3
  1514. ><P
  1515. >    The following contributors should be
  1516. recognized for the impact they have made and/or continue to make by adding
  1517. content to the manual:
  1518.    Jouni Ahto,              
  1519.    Alexander Aulbach,       
  1520.    Daniel Beckham,          
  1521.    Stig Bakken,             
  1522.    Jesus M. Castagnetto,    
  1523.    Ron Chmara,              
  1524.    John Coggeshall,         
  1525.    Simone Cortesi,          
  1526.    Markus Fischer,          
  1527.    Wez Furlong,             
  1528.    Sara Golemon,            
  1529.    Rui Hirokawa,            
  1530.    Brad House,              
  1531.    Moriyoshi Koizumi,       
  1532.    Rasmus Lerdorf,          
  1533.    Andrew Lindeman,         
  1534.    Stanislav Malyshev,      
  1535.    Rafael Martinez,         
  1536.    Yasuo Ohgaki,            
  1537.    Derick Rethans,          
  1538.    Sander Roobol,           
  1539.    Egon Schmid,             
  1540.    Thomas Schoefbeck,       
  1541.    Sascha Schumann,         
  1542.    Lars Torben Wilson,      
  1543.    Jim Winstead,            
  1544.    Jeroen van Wolffelaar and  
  1545.    Andrei Zmievski.         
  1546.   </P
  1547. ><P
  1548. >    The following contributors have done
  1549. significant work editing the manual:
  1550.    Stig Bakken,                    
  1551.    Hartmut Holzgraefe and  
  1552.    Egon Schmid.                    
  1553.   </P
  1554. ></DIV
  1555. ><DIV
  1556. CLASS="sect2"
  1557. ><HR><H3
  1558. CLASS="sect2"
  1559. ><A
  1560. NAME="AEN73"
  1561. >User Note Maintainers</A
  1562. ></H3
  1563. ><P
  1564. >    The currently most active maintainers are:
  1565.    Mehdi Achour,                
  1566.    Friedhelm Betz,              
  1567.    Vincent Gevers,              
  1568.    Aidan Lister,                
  1569.    Nuno Lopes and       
  1570.    Tom Sommer.                  
  1571.   </P
  1572. ><P
  1573. >    These people have also put a lot of effort
  1574. into managing user notes:
  1575.    Daniel Beckham,         
  1576.    Victor Boivie,          
  1577.    Jesus M. Castagnetto,   
  1578.    Nicolas Chaillan,       
  1579.    Ron Chmara,             
  1580.    James Cox,              
  1581.    Sara Golemon,           
  1582.    Zak Greant,             
  1583.    Szabolcs Heilig,        
  1584.    Oliver Hinckel,         
  1585.    Hartmut Holzgraefe,     
  1586.    Rasmus Lerdorf,         
  1587.    Andrew Lindeman,        
  1588.    Maxim Maletsky,         
  1589.    James Moore,            
  1590.    Sebastian Picklum,      
  1591.    Derick Rethans,         
  1592.    Sander Roobol,          
  1593.    Damien Seguy,           
  1594.    Jason Sheets,           
  1595.    Jani Taskinen,          
  1596.    Yasuo Ohgaki,           
  1597.    Philip Olson,           
  1598.    Lars Torben Wilson,     
  1599.    Jim Winstead,           
  1600.    Jared Wyles and  
  1601.    Jeroen van Wolffelaar.  
  1602.   </P
  1603. ></DIV
  1604. ></DIV
  1605. ></DIV
  1606. ><DIV
  1607. CLASS="PART"
  1608. ><A
  1609. NAME="getting-started"
  1610. ></A
  1611. ><DIV
  1612. CLASS="TITLEPAGE"
  1613. ><H1
  1614. CLASS="title"
  1615. >I. Getting Started</H1
  1616. ><DIV
  1617. CLASS="TOC"
  1618. ><DL
  1619. ><DT
  1620. ><B
  1621. >Table of Contents</B
  1622. ></DT
  1623. ><DT
  1624. >1. <A
  1625. HREF="#introduction"
  1626. >Introduction</A
  1627. ></DT
  1628. ><DT
  1629. >2. <A
  1630. HREF="#tutorial"
  1631. >A simple tutorial</A
  1632. ></DT
  1633. ></DL
  1634. ></DIV
  1635. ></DIV
  1636. ><DIV
  1637. CLASS="chapter"
  1638. ><HR><H1
  1639. ><A
  1640. NAME="introduction"
  1641. >Chapter 1. Introduction</A
  1642. ></H1
  1643. ><DIV
  1644. CLASS="sect1"
  1645. ><H2
  1646. CLASS="sect1"
  1647. ><A
  1648. NAME="intro-whatis"
  1649. >What is PHP?</A
  1650. ></H2
  1651. ><P
  1652. >     <ACRONYM
  1653. CLASS="acronym"
  1654. >PHP</ACRONYM
  1655. > (recursive acronym for "PHP: Hypertext
  1656.     Preprocessor") is a widely-used Open Source general-purpose
  1657.     scripting language that is especially suited for Web
  1658.     development and can be embedded into HTML.
  1659.    </P
  1660. ><P
  1661. >     Simple answer, but what does that mean? An example:
  1662.    </P
  1663. ><P
  1664. >     <TABLE
  1665. WIDTH="100%"
  1666. BORDER="0"
  1667. CELLPADDING="0"
  1668. CELLSPACING="0"
  1669. CLASS="EXAMPLE"
  1670. ><TR
  1671. ><TD
  1672. ><DIV
  1673. CLASS="example"
  1674. ><A
  1675. NAME="AEN87"
  1676. ></A
  1677. ><P
  1678. ><B
  1679. >Example 1-1. An introductory example</B
  1680. ></P
  1681. ><TABLE
  1682. BORDER="0"
  1683. BGCOLOR="#E0E0E0"
  1684. CELLPADDING="5"
  1685. ><TR
  1686. ><TD
  1687. ><PRE
  1688. CLASS="php"
  1689. ><html>
  1690.     <head>
  1691.         <title>Example</title>
  1692.     </head>
  1693.     <body>
  1694.  
  1695.         <?php 
  1696.         echo "Hi, I'm a PHP script!"; 
  1697.         ?>
  1698.  
  1699.     </body>
  1700. </html></PRE
  1701. ></TD
  1702. ></TR
  1703. ></TABLE
  1704. ></DIV
  1705. ></TD
  1706. ></TR
  1707. ></TABLE
  1708. >
  1709.    </P
  1710. ><P
  1711. >     Notice how this is different from a script written in other
  1712.     languages like Perl or C -- instead of writing a program with lots
  1713.     of commands to output HTML, you write an HTML script with some
  1714.     embedded code to do something (in this case, output some
  1715.     text). The PHP code is enclosed in special <A
  1716. HREF="#language.basic-syntax.phpmode"
  1717. >start and end tags</A
  1718. >
  1719.     that allow you to jump into and out of "PHP mode".
  1720.    </P
  1721. ><P
  1722. >     What distinguishes PHP from something like client-side JavaScript
  1723.     is that the code is executed on the server. If you were to have a
  1724.     script similar to the above on your server, the client would receive
  1725.     the results of running that script, with no way of determining what
  1726.     the underlying code may be. You can even configure your web server
  1727.     to process all your HTML files with PHP, and then there's really no
  1728.     way that users can tell what you have up your sleeve.
  1729.    </P
  1730. ><P
  1731. >     The best things in using PHP are that it is extremely simple
  1732.     for a newcomer, but offers many advanced features for
  1733.     a professional programmer. Don't be afraid reading the long
  1734.     list of PHP's features. You can jump in, in a short time, and
  1735.     start writing simple scripts in a few hours.
  1736.    </P
  1737. ><P
  1738. >     Although PHP's development is focused on server-side scripting,
  1739.     you can do much more with it. Read on, and see more in the
  1740.     <A
  1741. HREF="#intro-whatcando"
  1742. >What can PHP do?</A
  1743. > section,
  1744.     or go right to the <A
  1745. HREF="#tutorial"
  1746. >introductory
  1747.     tutorial</A
  1748. > if you are only interested in web programming.
  1749.    </P
  1750. ></DIV
  1751. ><DIV
  1752. CLASS="sect1"
  1753. ><HR><H2
  1754. CLASS="sect1"
  1755. ><A
  1756. NAME="intro-whatcando"
  1757. >What can PHP do?</A
  1758. ></H2
  1759. ><P
  1760. >     Anything. PHP is mainly focused on server-side scripting,
  1761.     so you can do anything any other CGI program can do, such
  1762.     as collect form data, generate dynamic page content, or
  1763.     send and receive cookies. But PHP can do much more.
  1764.    </P
  1765. ><P
  1766. >     There are three main areas where PHP scripts are used.
  1767.     <P
  1768. ></P
  1769. ><UL
  1770. ><LI
  1771. ><P
  1772. >        Server-side scripting. This is the most traditional
  1773.        and main target field for PHP. You need three things
  1774.        to make this work. The PHP parser (CGI or server
  1775.        module), a webserver and a web browser. You need to
  1776.        run the webserver, with a connected PHP installation.
  1777.        You can access the PHP program output with a web browser,
  1778.        viewing the PHP page through the server. All these can
  1779.        run on your home machine if you are just experimenting
  1780.        with PHP programming. See the
  1781.        <A
  1782. HREF="#install"
  1783. >installation instructions</A
  1784. >
  1785.        section for more information.
  1786.       </P
  1787. ></LI
  1788. ><LI
  1789. ><P
  1790. >        Command line scripting. You can make a PHP script
  1791.        to run it without any server or browser.
  1792.        You only need the PHP parser to use it this way.
  1793.        This type of usage is ideal for scripts regularly
  1794.        executed using cron (on *nix or Linux) or Task Scheduler (on
  1795.        Windows). These scripts can also be used for simple text
  1796.        processing tasks. See the section about 
  1797.        <A
  1798. HREF="#features.commandline"
  1799. >Command line usage of PHP</A
  1800. >
  1801.        for more information.
  1802.       </P
  1803. ></LI
  1804. ><LI
  1805. ><P
  1806. >        Writing desktop applications. PHP is probably
  1807.        not the very best language to create a desktop
  1808.        application with a graphical user interface, but if
  1809.        you know PHP very well, and would like to use some
  1810.        advanced PHP features in your client-side applications
  1811.        you can also use PHP-GTK to write such programs. You also
  1812.        have the ability to write cross-platform applications this
  1813.        way. PHP-GTK is an extension to PHP, not available in
  1814.        the main distribution. If you are interested
  1815.        in PHP-GTK, visit <A
  1816. HREF="http://gtk.php.net/"
  1817. TARGET="_top"
  1818. >its
  1819.        own website</A
  1820. >.
  1821.       </P
  1822. ></LI
  1823. ></UL
  1824. >
  1825.    </P
  1826. ><P
  1827. >     PHP can be used on all major operating systems, including
  1828.     Linux, many Unix variants (including HP-UX, Solaris and OpenBSD),
  1829.     Microsoft Windows, Mac OS X, RISC OS, and probably others.
  1830.     PHP has also support for most of the web servers today. This
  1831.     includes Apache, Microsoft Internet Information Server,
  1832.     Personal Web Server, Netscape and iPlanet servers, Oreilly
  1833.     Website Pro server, Caudium, Xitami, OmniHTTPd, and many
  1834.     others. For the majority of the servers PHP has a module,
  1835.     for the others supporting the CGI standard, PHP can work
  1836.     as a CGI processor.
  1837.    </P
  1838. ><P
  1839. >     So with PHP, you have the freedom of choosing an operating
  1840.     system and a web server. Furthermore, you also have the choice
  1841.     of using procedural programming or object oriented
  1842.     programming, or a mixture of them. Although not every
  1843.     standard OOP feature is implemented in PHP 4,
  1844.     many code libraries and large applications (including
  1845.     the PEAR library) are written only using OOP code. PHP 5 fixes the
  1846.     OOP related weaknesses of PHP 4, and introduces a complete object
  1847.     model.
  1848.    </P
  1849. ><P
  1850. >     With PHP you are not limited to output HTML. PHP's abilities
  1851.     includes outputting images, PDF files and even Flash movies
  1852.     (using libswf and Ming) generated on the fly. You can also
  1853.     output easily any text, such as XHTML and any other XML file.
  1854.     PHP can autogenerate these files, and save them in the file
  1855.     system, instead of printing it out, forming a server-side
  1856.     cache for your dynamic content.
  1857.    </P
  1858. ><P
  1859. >     One of the strongest and most significant features in PHP is its
  1860.     support for a wide range of databases. Writing a database-enabled
  1861.     web page is incredibly simple. The following databases are currently
  1862.     supported:
  1863.     <A
  1864. NAME="AEN115"
  1865. ></A
  1866. ><BLOCKQUOTE
  1867. CLASS="BLOCKQUOTE"
  1868. ><P
  1869. ></P
  1870. ><TABLE
  1871. BORDER="0"
  1872. ><TBODY
  1873. ><TR
  1874. ><TD
  1875. >Adabas D</TD
  1876. ><TD
  1877. >InterBase</TD
  1878. ><TD
  1879. >PostgreSQL</TD
  1880. ></TR
  1881. ><TR
  1882. ><TD
  1883. >dBase</TD
  1884. ><TD
  1885. >FrontBase</TD
  1886. ><TD
  1887. >SQLite</TD
  1888. ></TR
  1889. ><TR
  1890. ><TD
  1891. >Empress</TD
  1892. ><TD
  1893. >mSQL</TD
  1894. ><TD
  1895. >Solid</TD
  1896. ></TR
  1897. ><TR
  1898. ><TD
  1899. >FilePro (read-only)</TD
  1900. ><TD
  1901. >Direct MS-SQL</TD
  1902. ><TD
  1903. >Sybase</TD
  1904. ></TR
  1905. ><TR
  1906. ><TD
  1907. >Hyperwave</TD
  1908. ><TD
  1909. >MySQL</TD
  1910. ><TD
  1911. >Velocis</TD
  1912. ></TR
  1913. ><TR
  1914. ><TD
  1915. >IBM DB2</TD
  1916. ><TD
  1917. >ODBC</TD
  1918. ><TD
  1919. >Unix dbm</TD
  1920. ></TR
  1921. ><TR
  1922. ><TD
  1923. >Informix</TD
  1924. ><TD
  1925. >Oracle (OCI7 and OCI8)</TD
  1926. ><TD
  1927. > </TD
  1928. ></TR
  1929. ><TR
  1930. ><TD
  1931. >Ingres</TD
  1932. ><TD
  1933. >Ovrimos</TD
  1934. ><TD
  1935. > </TD
  1936. ></TR
  1937. ></TBODY
  1938. ></TABLE
  1939. ><P
  1940. ></P
  1941. ></BLOCKQUOTE
  1942. >
  1943.     We also have a DBX database abstraction extension allowing you
  1944.     to transparently use any database supported by that extension.
  1945.     Additionally PHP supports ODBC, the Open Database Connection
  1946.     standard, so you can connect to any other database supporting
  1947.     this world standard.
  1948.    </P
  1949. ><P
  1950. >     PHP also has support for talking to other services using protocols
  1951.     such as LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (on Windows) and
  1952.     countless others. You can also open raw network sockets and
  1953.     interact using any other protocol. PHP has support for the WDDX
  1954.     complex data exchange between virtually all Web programming
  1955.     languages. Talking about interconnection, PHP has support for
  1956.     instantiation of Java objects and using them transparently
  1957.     as PHP objects. You can also use our CORBA extension to
  1958.     access remote objects.
  1959.    </P
  1960. ><P
  1961. >     PHP has extremely useful text processing features, from the
  1962.     POSIX Extended or Perl regular expressions to parsing XML
  1963.     documents. For parsing and accessing XML documents, PHP 4
  1964.     supports the SAX and DOM standards, and you can also use the
  1965.     XSLT extension to transform XML documents. PHP 5 standardizes
  1966.     all the XML extensions on the solid base of libxml2 and extends
  1967.     the feature set adding SimpleXML and XMLReader support.
  1968.    </P
  1969. ><P
  1970. >     While using PHP in the e-commerce field, you'll find
  1971.     the Cybercash payment, CyberMUT, VeriSign Payflow
  1972.     Pro and MCVE functions useful for your online payment
  1973.     programs.
  1974.    </P
  1975. ><P
  1976. >     At last but not least, we have many other interesting
  1977.     extensions, the mnoGoSearch search engine functions,
  1978.     the IRC Gateway functions, many compression utilities
  1979.     (gzip, bz2), calendar conversion, translation...
  1980.    </P
  1981. ><P
  1982. >     As you can see this page is not enough to list all
  1983.     the features and benefits PHP can offer. Read on in
  1984.     the sections about <A
  1985. HREF="#install"
  1986. >installing
  1987.     PHP</A
  1988. >, and see the <A
  1989. HREF="#funcref"
  1990. >function
  1991.     reference</A
  1992. > part for explanation of the extensions
  1993.     mentioned here.
  1994.    </P
  1995. ></DIV
  1996. ></DIV
  1997. ><DIV
  1998. CLASS="chapter"
  1999. ><HR><H1
  2000. ><A
  2001. NAME="tutorial"
  2002. >Chapter 2. A simple tutorial</A
  2003. ></H1
  2004. ><P
  2005. >    Here we would like to show the very basics of PHP in a short, simple
  2006.    tutorial. This text only deals with dynamic webpage creation with
  2007.    PHP, though PHP is not only capable of creating webpages. See
  2008.    the section titled <A
  2009. HREF="#intro-whatcando"
  2010. >What can PHP
  2011.    do</A
  2012. > for more information.
  2013.   </P
  2014. ><P
  2015. >    PHP-enabled web pages are treated just like regular HTML pages and
  2016.    you can create and edit them the same way you normally create
  2017.    regular HTML pages.
  2018.   </P
  2019. ><DIV
  2020. CLASS="sect1"
  2021. ><HR><H2
  2022. CLASS="sect1"
  2023. ><A
  2024. NAME="tutorial.requirements"
  2025. >What do I need?</A
  2026. ></H2
  2027. ><P
  2028. >     In this tutorial we assume that your server has activated support 
  2029.     for PHP and that all files ending in <TT
  2030. CLASS="filename"
  2031. >.php</TT
  2032. >
  2033.     are handled by PHP. On most servers, this is the default extension
  2034.     for PHP files, but ask your server administrator to be sure. If
  2035.     your server supports PHP, then you do not need to do anything. Just
  2036.     create your <TT
  2037. CLASS="filename"
  2038. >.php</TT
  2039. > files, put them in your
  2040.     web directory and the server will automatically parse them for you.
  2041.     There is no need to compile anything nor do you need to install
  2042.     any extra tools. Think of these PHP-enabled files as simple HTML
  2043.     files with a whole new family of magical tags that let you do all
  2044.     sorts of things.  Most web hosts offer PHP support, but if your
  2045.     host does not, consider reading the <A
  2046. HREF="http://www.php.net/links.php"
  2047. TARGET="_top"
  2048. >     PHP Links</A
  2049. > section for resources on finding PHP enabled
  2050.     web hosts.
  2051.    </P
  2052. ><P
  2053. >     Let us say you want to save precious bandwidth and develop locally.  
  2054.     In this case, you will want to install a web server, such as 
  2055.     <A
  2056. HREF="http://www.apache.org/"
  2057. TARGET="_top"
  2058. >Apache</A
  2059. >, and of course 
  2060.     <A
  2061. HREF="http://www.php.net/downloads.php"
  2062. TARGET="_top"
  2063. >PHP</A
  2064. >. You will most likely 
  2065.     want to install a database as well, such as 
  2066.     <A
  2067. HREF="http://dev.mysql.com/doc/"
  2068. TARGET="_top"
  2069. >MySQL</A
  2070. >.
  2071.    </P
  2072. ><P
  2073. >     You can either install these individually or choose a simpler way. Our
  2074.     manual has <A
  2075. HREF="#install"
  2076. >installation instructions for
  2077.     PHP</A
  2078. > (assuming you already have some webserver set up). In case
  2079.     you have problems with installing PHP yourself, we would suggest you ask
  2080.     your questions on our <A
  2081. HREF="http://www.php.net/mailing-lists.php"
  2082. TARGET="_top"
  2083. >installation
  2084.     mailing list</A
  2085. >. If you choose to go on the simpler route, then
  2086.     <A
  2087. HREF="http://www.hotscripts.com/PHP/Software_and_Servers/Installation_Kits/"
  2088. TARGET="_top"
  2089. >locate a pre-configured package</A
  2090. >
  2091.     for your operating system,  which automatically installs all of these
  2092.     with just a few mouse clicks. It is easy to setup a web server with PHP
  2093.     support on any operating system, including MacOSX, Linux and Windows.
  2094.     On Linux, you may find <A
  2095. HREF="http://www.rpmfind.net/"
  2096. TARGET="_top"
  2097. >rpmfind</A
  2098. > and
  2099.     <A
  2100. HREF="http://rpm.pbone.net/"
  2101. TARGET="_top"
  2102. >PBone</A
  2103. > helpful for
  2104.     locating RPMs. You may also want to visit <A
  2105. HREF="http://www.apt-get.org/"
  2106. TARGET="_top"
  2107. >apt-get</A
  2108. > to find packages for Debian.
  2109.    </P
  2110. ></DIV
  2111. ><DIV
  2112. CLASS="sect1"
  2113. ><HR><H2
  2114. CLASS="sect1"
  2115. ><A
  2116. NAME="tutorial.firstpage"
  2117. >Your first PHP-enabled page</A
  2118. ></H2
  2119. ><P
  2120. >     Create a file named <TT
  2121. CLASS="filename"
  2122. >hello.php</TT
  2123. > and put it
  2124.     in your web server's root directory (<VAR
  2125. CLASS="varname"
  2126. >DOCUMENT_ROOT</VAR
  2127. >) 
  2128.     with the following content:
  2129.    </P
  2130. ><P
  2131. >     <TABLE
  2132. WIDTH="100%"
  2133. BORDER="0"
  2134. CELLPADDING="0"
  2135. CELLSPACING="0"
  2136. CLASS="EXAMPLE"
  2137. ><TR
  2138. ><TD
  2139. ><DIV
  2140. CLASS="example"
  2141. ><A
  2142. NAME="AEN174"
  2143. ></A
  2144. ><P
  2145. ><B
  2146. >Example 2-1. Our first PHP script: <TT
  2147. CLASS="filename"
  2148. >hello.php</TT
  2149. ></B
  2150. ></P
  2151. ><TABLE
  2152. BORDER="0"
  2153. BGCOLOR="#E0E0E0"
  2154. CELLPADDING="5"
  2155. ><TR
  2156. ><TD
  2157. ><PRE
  2158. CLASS="php"
  2159. ><html>
  2160.  <head>
  2161.   <title>PHP Test</title>
  2162.  </head>
  2163.  <body>
  2164.  <?php echo '<p>Hello World</p>'; ?>
  2165.  </body>
  2166. </html></PRE
  2167. ></TD
  2168. ></TR
  2169. ></TABLE
  2170. ><P
  2171. >       Use your browser to access the file with your web server's URL, ending
  2172.       with the "/hello.php" file reference. When developing locally this
  2173.       URL will be something like <VAR
  2174. CLASS="literal"
  2175. >http://localhost/hello.php</VAR
  2176. > 
  2177.       or <VAR
  2178. CLASS="literal"
  2179. >http://127.0.0.1/hello.php</VAR
  2180. > but this depends on the
  2181.       web server's configuration. If everything is configured correctly, this
  2182.       file will be parsed by PHP and the following output will be sent to
  2183.       your browser:
  2184.      </P
  2185. ><TABLE
  2186. BORDER="0"
  2187. BGCOLOR="#E0E0E0"
  2188. CELLPADDING="5"
  2189. ><TR
  2190. ><TD
  2191. ><PRE
  2192. CLASS="html"
  2193. ><html>
  2194.  <head>
  2195.   <title>PHP Test</title>
  2196.  </head>
  2197.  <body>
  2198.  <p>Hello World</p>
  2199.  </body>
  2200. </html></PRE
  2201. ></TD
  2202. ></TR
  2203. ></TABLE
  2204. ></DIV
  2205. ></TD
  2206. ></TR
  2207. ></TABLE
  2208. >
  2209.    </P
  2210. ><P
  2211. >     This program is extremely simple and you really did not need to use
  2212.     PHP to create a page like this. All it does is display:
  2213.     <VAR
  2214. CLASS="literal"
  2215. >Hello World</VAR
  2216. > using the PHP <A
  2217. HREF="#function.echo"
  2218. ><B
  2219. CLASS="function"
  2220. >echo()</B
  2221. ></A
  2222. >
  2223.     statement. Note that the file <SPAN
  2224. CLASS="emphasis"
  2225. ><I
  2226. CLASS="emphasis"
  2227. >does not need to be executable</I
  2228. ></SPAN
  2229. >
  2230.     or special in any way. The server finds out that this file needs to be interpreted
  2231.     by PHP because you used the ".php" extension, which the server is configured
  2232.     to pass on to PHP. Think of this as a normal HTML file which happens to have
  2233.     a set of special tags available to you that do a lot of interesting things.
  2234.    </P
  2235. ><P
  2236. >     If you tried this example and it did not output anything, it prompted 
  2237.     for download, or you see the whole file as text, chances are that the 
  2238.     server you are on does not have PHP enabled, or is not configured properly.
  2239.     Ask your administrator to enable it for you using the
  2240.     <A
  2241. HREF="#install"
  2242. >Installation</A
  2243. > chapter 
  2244.     of the manual. If you are developing locally, also read the
  2245.     installation chapter to make sure everything is configured
  2246.     properly. Make sure that you access the file via http with the server
  2247.     providing you the output. If you just call up the file from your file
  2248.     system, then it will not be parsed by PHP. If the problems persist anyway,
  2249.     do not hesitate to use one of the many
  2250.     <A
  2251. HREF="http://www.php.net/support.php"
  2252. TARGET="_top"
  2253. >PHP support</A
  2254. > options.
  2255.    </P
  2256. ><P
  2257. >     The point of the example is to show the special PHP tag format.
  2258.     In this example we used <VAR
  2259. CLASS="literal"
  2260. ><?php</VAR
  2261. > to indicate the
  2262.     start of a PHP tag. Then we put the PHP statement and left PHP mode by
  2263.     adding the closing tag, <VAR
  2264. CLASS="literal"
  2265. >?></VAR
  2266. >. You may jump in
  2267.     and out of PHP mode in an HTML file like this anywhere you want.  For more
  2268.     details, read the manual section on the <A
  2269. HREF="#language.basic-syntax"
  2270. >     basic PHP syntax</A
  2271. >.
  2272.    </P
  2273. ><DIV
  2274. CLASS="note"
  2275. ><BLOCKQUOTE
  2276. CLASS="note"
  2277. ><P
  2278. ><B
  2279. >A Note on Text Editors: </B
  2280. >
  2281.      There are many text editors and Integrated Development Environments (IDEs)
  2282.      that you can use to create, edit and manage PHP files. A partial list of 
  2283.      these tools is maintained at <A
  2284. HREF="http://www.thelinuxconsultancy.co.uk/phpeditors/"
  2285. TARGET="_top"
  2286. >PHP Editors
  2287.      List</A
  2288. >. If you wish to recommend an editor, please visit the above
  2289.      page and ask the page maintainer to add the editor to the list.  Having
  2290.      an editor with syntax highlighting can be helpful.
  2291.     </P
  2292. ></BLOCKQUOTE
  2293. ></DIV
  2294. ><DIV
  2295. CLASS="note"
  2296. ><BLOCKQUOTE
  2297. CLASS="note"
  2298. ><P
  2299. ><B
  2300. >A Note on Word Processors: </B
  2301. >
  2302.      Word processors such as StarOffice Writer, Microsoft Word and Abiword are
  2303.      not optimal for editing PHP files.  If you wish to use one for this 
  2304.      test script, you must ensure that you save the file as <SPAN
  2305. CLASS="emphasis"
  2306. ><I
  2307. CLASS="emphasis"
  2308. >plain
  2309.      text</I
  2310. ></SPAN
  2311. > or PHP will not be able to read and execute the script.
  2312.     </P
  2313. ></BLOCKQUOTE
  2314. ></DIV
  2315. ><DIV
  2316. CLASS="note"
  2317. ><BLOCKQUOTE
  2318. CLASS="note"
  2319. ><P
  2320. ><B
  2321. >A Note on Windows Notepad: </B
  2322. >
  2323.      If you are writing your PHP scripts using Windows Notepad, you will need
  2324.      to ensure that your files are saved with the .php extension. (Notepad adds
  2325.      a .txt extension to files automatically unless you take one of the
  2326.      following steps to prevent it.)  When you save the file and are prompted
  2327.      to provide a name for the file, place the filename in quotes 
  2328.      (i.e. "<TT
  2329. CLASS="filename"
  2330. >hello.php</TT
  2331. >").  Alternatively, you can click on the 
  2332.      'Text Documents' drop-down menu in the 'Save' dialog box and change the setting 
  2333.      to "All Files". You can then enter your filename without quotes.
  2334.     </P
  2335. ></BLOCKQUOTE
  2336. ></DIV
  2337. ><P
  2338. >     Now that you have successfully created a working PHP script, it is
  2339.     time to create the most famous PHP script!  Make a call to the
  2340.     <A
  2341. HREF="#function.phpinfo"
  2342. ><B
  2343. CLASS="function"
  2344. >phpinfo()</B
  2345. ></A
  2346. > function and you will see a lot of useful
  2347.     information about your system and setup such as available
  2348.     <A
  2349. HREF="#language.variables.predefined"
  2350. >predefined variables</A
  2351. >, 
  2352.     loaded PHP modules, and <A
  2353. HREF="#configuration"
  2354. >configuration</A
  2355. >
  2356.     settings. Take some time and review this important information.
  2357.    </P
  2358. ><P
  2359. >     <TABLE
  2360. WIDTH="100%"
  2361. BORDER="0"
  2362. CELLPADDING="0"
  2363. CELLSPACING="0"
  2364. CLASS="EXAMPLE"
  2365. ><TR
  2366. ><TD
  2367. ><DIV
  2368. CLASS="example"
  2369. ><A
  2370. NAME="AEN210"
  2371. ></A
  2372. ><P
  2373. ><B
  2374. >Example 2-2. Get system information from PHP</B
  2375. ></P
  2376. ><TABLE
  2377. BORDER="0"
  2378. BGCOLOR="#E0E0E0"
  2379. CELLPADDING="5"
  2380. ><TR
  2381. ><TD
  2382. ><PRE
  2383. CLASS="php"
  2384. ><?php phpinfo(); ?></PRE
  2385. ></TD
  2386. ></TR
  2387. ></TABLE
  2388. ></DIV
  2389. ></TD
  2390. ></TR
  2391. ></TABLE
  2392. >
  2393.    </P
  2394. ></DIV
  2395. ><DIV
  2396. CLASS="sect1"
  2397. ><HR><H2
  2398. CLASS="sect1"
  2399. ><A
  2400. NAME="tutorial.useful"
  2401. >Something Useful</A
  2402. ></H2
  2403. ><P
  2404. >     Let us do something more useful now. We are going to check
  2405.     what sort of browser the visitor is using.
  2406.     For that, we check the user agent string the browser
  2407.     sends as part of the HTTP request. This information is stored in a <A
  2408. HREF="#language.variables"
  2409. >variable</A
  2410. >. Variables always start
  2411.     with a dollar-sign in PHP. The variable we are interested in right now 
  2412.     is <VAR
  2413. CLASS="varname"
  2414. >$_SERVER['HTTP_USER_AGENT']</VAR
  2415. >.
  2416.    </P
  2417. ><DIV
  2418. CLASS="note"
  2419. ><BLOCKQUOTE
  2420. CLASS="note"
  2421. ><P
  2422. ><B
  2423. >Note: </B
  2424. >
  2425.      <A
  2426. HREF="#reserved.variables.server"
  2427. >$_SERVER</A
  2428. > is a 
  2429.      special reserved PHP variable that contains all web server information.
  2430.      It is known as an autoglobal (or superglobal).  See the related manual page on
  2431.      <A
  2432. HREF="#language.variables.superglobals"
  2433. >superglobals</A
  2434. >
  2435.      for more information.  These special variables were introduced in PHP 
  2436.      <A
  2437. HREF="http://www.php.net/release_4_1_0.php"
  2438. TARGET="_top"
  2439. >4.1.0</A
  2440. >.  Before this time, we used
  2441.      the older <VAR
  2442. CLASS="varname"
  2443. >$HTTP_*_VARS</VAR
  2444. > arrays instead,
  2445.      such as <VAR
  2446. CLASS="varname"
  2447. >$HTTP_SERVER_VARS</VAR
  2448. >.  Although deprecated, 
  2449.      these older variables still exist.  (See also the note on
  2450.      <A
  2451. HREF="#tutorial.oldcode"
  2452. >old code</A
  2453. >.)
  2454.     </P
  2455. ></BLOCKQUOTE
  2456. ></DIV
  2457. ><P
  2458. >     To display this variable, you can simply do:
  2459.    </P
  2460. ><P
  2461. >     <TABLE
  2462. WIDTH="100%"
  2463. BORDER="0"
  2464. CELLPADDING="0"
  2465. CELLSPACING="0"
  2466. CLASS="EXAMPLE"
  2467. ><TR
  2468. ><TD
  2469. ><DIV
  2470. CLASS="example"
  2471. ><A
  2472. NAME="AEN228"
  2473. ></A
  2474. ><P
  2475. ><B
  2476. >Example 2-3. Printing a variable (Array element)</B
  2477. ></P
  2478. ><TABLE
  2479. BORDER="0"
  2480. BGCOLOR="#E0E0E0"
  2481. CELLPADDING="5"
  2482. ><TR
  2483. ><TD
  2484. ><PRE
  2485. CLASS="php"
  2486. ><?php echo $_SERVER['HTTP_USER_AGENT']; ?></PRE
  2487. ></TD
  2488. ></TR
  2489. ></TABLE
  2490. ><P
  2491. >      A sample output of this script may be:
  2492.     </P
  2493. ><TABLE
  2494. BORDER="0"
  2495. BGCOLOR="#E0E0E0"
  2496. CELLPADDING="5"
  2497. ><TR
  2498. ><TD
  2499. ><PRE
  2500. CLASS="html"
  2501. >Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)</PRE
  2502. ></TD
  2503. ></TR
  2504. ></TABLE
  2505. ></DIV
  2506. ></TD
  2507. ></TR
  2508. ></TABLE
  2509. >
  2510.    </P
  2511. ><P
  2512. >     There are many <A
  2513. HREF="#language.types"
  2514. >types</A
  2515. > of 
  2516.     variables available in PHP.  In the above example we printed 
  2517.     an <A
  2518. HREF="#language.types.array"
  2519. >Array</A
  2520. > element.
  2521.     Arrays can be very useful.
  2522.    </P
  2523. ><P
  2524. >     <VAR
  2525. CLASS="varname"
  2526. >$_SERVER</VAR
  2527. > is just one variable that PHP automatically 
  2528.     makes available to you. A list can be seen in the 
  2529.     <A
  2530. HREF="#reserved.variables"
  2531. >Reserved Variables</A
  2532. > section 
  2533.     of the manual or you can get a complete list of them by looking at
  2534.     the output of the <A
  2535. HREF="#function.phpinfo"
  2536. ><B
  2537. CLASS="function"
  2538. >phpinfo()</B
  2539. ></A
  2540. > function used in the
  2541.     example in the previous section.
  2542.    </P
  2543. ><P
  2544. >     You can put multiple PHP statements inside a PHP tag and create
  2545.     little blocks of code that do more than just a single echo.
  2546.     For example, if you want to check for Internet Explorer you
  2547.     can do this:
  2548.    </P
  2549. ><P
  2550. >     <TABLE
  2551. WIDTH="100%"
  2552. BORDER="0"
  2553. CELLPADDING="0"
  2554. CELLSPACING="0"
  2555. CLASS="EXAMPLE"
  2556. ><TR
  2557. ><TD
  2558. ><DIV
  2559. CLASS="example"
  2560. ><A
  2561. NAME="AEN242"
  2562. ></A
  2563. ><P
  2564. ><B
  2565. >Example 2-4. Example using <A
  2566. HREF="#language.control-structures"
  2567. >control 
  2568.      structures</A
  2569. > and <A
  2570. HREF="#language.functions"
  2571. >functions</A
  2572. ></B
  2573. ></P
  2574. ><TABLE
  2575. BORDER="0"
  2576. BGCOLOR="#E0E0E0"
  2577. CELLPADDING="5"
  2578. ><TR
  2579. ><TD
  2580. ><PRE
  2581. CLASS="php"
  2582. ><?php
  2583. if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE) {
  2584.     echo 'You are using Internet Explorer.<br />';
  2585. }
  2586. ?></PRE
  2587. ></TD
  2588. ></TR
  2589. ></TABLE
  2590. ><P
  2591. >       A sample output of this script may be:
  2592.      </P
  2593. ><TABLE
  2594. BORDER="0"
  2595. BGCOLOR="#E0E0E0"
  2596. CELLPADDING="5"
  2597. ><TR
  2598. ><TD
  2599. ><PRE
  2600. CLASS="html"
  2601. >You are using Internet Explorer.<br /></PRE
  2602. ></TD
  2603. ></TR
  2604. ></TABLE
  2605. ></DIV
  2606. ></TD
  2607. ></TR
  2608. ></TABLE
  2609. >
  2610.    </P
  2611. ><P
  2612. >     Here we introduce a couple of new concepts. We have an 
  2613.     <A
  2614. HREF="#control-structures.if"
  2615. >if</A
  2616. > statement.
  2617.     If you are familiar with the basic syntax used by the C
  2618.     language, this should look logical to you. Otherwise, you
  2619.     should probably pick up an introductory PHP book and read the first
  2620.     couple of chapters, or read the <A
  2621. HREF="#langref"
  2622. >Language
  2623.     Reference</A
  2624. > part of the manual. You can find a list of PHP books
  2625.     at <A
  2626. HREF="http://www.php.net/books.php"
  2627. TARGET="_top"
  2628. >http://www.php.net/books.php</A
  2629. >.
  2630.    </P
  2631. ><P
  2632. >     The second concept we introduced was the <A
  2633. HREF="#function.strpos"
  2634. ><B
  2635. CLASS="function"
  2636. >strpos()</B
  2637. ></A
  2638. >
  2639.     function call. <A
  2640. HREF="#function.strpos"
  2641. ><B
  2642. CLASS="function"
  2643. >strpos()</B
  2644. ></A
  2645. > is a function built into
  2646.     PHP which searches a string for another string. In this case we are
  2647.     looking for <VAR
  2648. CLASS="literal"
  2649. >'MSIE'</VAR
  2650. > (so-called needle) inside
  2651.     <VAR
  2652. CLASS="varname"
  2653. >$_SERVER['HTTP_USER_AGENT']</VAR
  2654. > (so-called haystack).  If
  2655.     the needle is found inside the haystack, the function returns the position
  2656.     of the needle relative to the start of the haystack.  Otherwise, it
  2657.     returns <TT
  2658. CLASS="constant"
  2659. ><B
  2660. >FALSE</B
  2661. ></TT
  2662. >.  If it does not return <TT
  2663. CLASS="constant"
  2664. ><B
  2665. >FALSE</B
  2666. ></TT
  2667. >, the <A
  2668. HREF="#control-structures.if"
  2669. >if</A
  2670. > expression evaluates to <TT
  2671. CLASS="constant"
  2672. ><B
  2673. >TRUE</B
  2674. ></TT
  2675. >
  2676.     and the code within its {braces} is executed. Otherwise, the code is not
  2677.     run. Feel free to create similar examples, 
  2678.     with <A
  2679. HREF="#control-structures.if"
  2680. >if</A
  2681. >, 
  2682.     <A
  2683. HREF="#control-structures.else"
  2684. >else</A
  2685. >, and other 
  2686.     functions such as <A
  2687. HREF="#function.strtoupper"
  2688. ><B
  2689. CLASS="function"
  2690. >strtoupper()</B
  2691. ></A
  2692. > and 
  2693.     <A
  2694. HREF="#function.strlen"
  2695. ><B
  2696. CLASS="function"
  2697. >strlen()</B
  2698. ></A
  2699. >.  Each related manual page contains examples 
  2700.     too.  If you are unsure how to use functions, you will want to read both
  2701.     the manual page on <A
  2702. HREF="#about.prototypes"
  2703. >how to read a
  2704.     function definition</A
  2705. > and the section about  
  2706.     <A
  2707. HREF="#language.functions"
  2708. >PHP functions</A
  2709. >.
  2710.    </P
  2711. ><P
  2712. >     We can take this a step further and show how you can jump in and out
  2713.     of PHP mode even in the middle of a PHP block:
  2714.    </P
  2715. ><P
  2716. >     <TABLE
  2717. WIDTH="100%"
  2718. BORDER="0"
  2719. CELLPADDING="0"
  2720. CELLSPACING="0"
  2721. CLASS="EXAMPLE"
  2722. ><TR
  2723. ><TD
  2724. ><DIV
  2725. CLASS="example"
  2726. ><A
  2727. NAME="AEN270"
  2728. ></A
  2729. ><P
  2730. ><B
  2731. >Example 2-5. Mixing both HTML and PHP modes</B
  2732. ></P
  2733. ><TABLE
  2734. BORDER="0"
  2735. BGCOLOR="#E0E0E0"
  2736. CELLPADDING="5"
  2737. ><TR
  2738. ><TD
  2739. ><PRE
  2740. CLASS="php"
  2741. ><?php
  2742. if (strpos($_SERVER['HTTP_USER_AGENT'], 'MSIE') !== FALSE) {
  2743. ?>
  2744. <h3>strpos() must have returned non-false</h3>
  2745. <p>You are using Internet Explorer</p>
  2746. <?php
  2747. } else {
  2748. ?>
  2749. <h3>strpos() must have returned false</h3>
  2750. <p>You are not using Internet Explorer</p>
  2751. <?php
  2752. }
  2753. ?></PRE
  2754. ></TD
  2755. ></TR
  2756. ></TABLE
  2757. ><P
  2758. >       A sample output of this script may be:
  2759.      </P
  2760. ><TABLE
  2761. BORDER="0"
  2762. BGCOLOR="#E0E0E0"
  2763. CELLPADDING="5"
  2764. ><TR
  2765. ><TD
  2766. ><PRE
  2767. CLASS="html"
  2768. ><h3>strpos() must have returned non-false</h3>
  2769. <p>You are using Internet Explorer</p></PRE
  2770. ></TD
  2771. ></TR
  2772. ></TABLE
  2773. ></DIV
  2774. ></TD
  2775. ></TR
  2776. ></TABLE
  2777. >
  2778.    </P
  2779. ><P
  2780. >     Instead of using a PHP echo statement to output something, we jumped out
  2781.     of PHP mode and just sent straight HTML. The important and powerful point
  2782.     to note here is that the logical flow of the script remains intact. Only
  2783.     one of the HTML blocks will end up getting sent to the viewer depending on
  2784.     the result of <A
  2785. HREF="#function.strpos"
  2786. ><B
  2787. CLASS="function"
  2788. >strpos()</B
  2789. ></A
  2790. >.  In other words, it depends on
  2791.     whether the string <VAR
  2792. CLASS="literal"
  2793. >MSIE</VAR
  2794. > was found or not.
  2795.    </P
  2796. ></DIV
  2797. ><DIV
  2798. CLASS="sect1"
  2799. ><HR><H2
  2800. CLASS="sect1"
  2801. ><A
  2802. NAME="tutorial.forms"
  2803. >Dealing with Forms</A
  2804. ></H2
  2805. ><P
  2806. >     One of the most powerful features of PHP is the way it handles HTML
  2807.     forms. The basic concept that is important to understand is that any
  2808.     form element will automatically be available to your PHP 
  2809.     scripts.  Please read the manual section on
  2810.     <A
  2811. HREF="#language.variables.external"
  2812. >Variables from outside 
  2813.     of PHP</A
  2814. > for more information and examples on using forms 
  2815.     with PHP.  Here is an example HTML form:
  2816.    </P
  2817. ><P
  2818. >     <TABLE
  2819. WIDTH="100%"
  2820. BORDER="0"
  2821. CELLPADDING="0"
  2822. CELLSPACING="0"
  2823. CLASS="EXAMPLE"
  2824. ><TR
  2825. ><TD
  2826. ><DIV
  2827. CLASS="example"
  2828. ><A
  2829. NAME="AEN283"
  2830. ></A
  2831. ><P
  2832. ><B
  2833. >Example 2-6. A simple HTML form</B
  2834. ></P
  2835. ><TABLE
  2836. BORDER="0"
  2837. BGCOLOR="#E0E0E0"
  2838. CELLPADDING="5"
  2839. ><TR
  2840. ><TD
  2841. ><PRE
  2842. CLASS="html"
  2843. ><form action="action.php" method="post">
  2844.  <p>Your name: <input type="text" name="name" /></p>
  2845.  <p>Your age: <input type="text" name="age" /></p>
  2846.  <p><input type="submit" /></p>
  2847. </form></PRE
  2848. ></TD
  2849. ></TR
  2850. ></TABLE
  2851. ></DIV
  2852. ></TD
  2853. ></TR
  2854. ></TABLE
  2855. >
  2856.    </P
  2857. ><P
  2858. >     There is nothing special about this form. It is a straight HTML form
  2859.     with no special tags of any kind. When the user fills in this form
  2860.     and hits the submit button, the <TT
  2861. CLASS="filename"
  2862. >action.php</TT
  2863. > page
  2864.     is called. In this file you would write something like this:
  2865.    </P
  2866. ><P
  2867. >     <TABLE
  2868. WIDTH="100%"
  2869. BORDER="0"
  2870. CELLPADDING="0"
  2871. CELLSPACING="0"
  2872. CLASS="EXAMPLE"
  2873. ><TR
  2874. ><TD
  2875. ><DIV
  2876. CLASS="example"
  2877. ><A
  2878. NAME="AEN289"
  2879. ></A
  2880. ><P
  2881. ><B
  2882. >Example 2-7. Printing data from our form</B
  2883. ></P
  2884. ><TABLE
  2885. BORDER="0"
  2886. BGCOLOR="#E0E0E0"
  2887. CELLPADDING="5"
  2888. ><TR
  2889. ><TD
  2890. ><PRE
  2891. CLASS="php"
  2892. >Hi <?php echo $_POST['name']; ?>.
  2893. You are <?php echo $_POST['age']; ?> years old.</PRE
  2894. ></TD
  2895. ></TR
  2896. ></TABLE
  2897. ><P
  2898. >       A sample output of this script may be:
  2899.      </P
  2900. ><TABLE
  2901. BORDER="0"
  2902. BGCOLOR="#E0E0E0"
  2903. CELLPADDING="5"
  2904. ><TR
  2905. ><TD
  2906. ><PRE
  2907. CLASS="html"
  2908. >Hi Joe. You are 22 years old.</PRE
  2909. ></TD
  2910. ></TR
  2911. ></TABLE
  2912. ></DIV
  2913. ></TD
  2914. ></TR
  2915. ></TABLE
  2916. >
  2917.    </P
  2918. ><P
  2919. >     It should be obvious what this does. There is nothing more to it.
  2920.     The <VAR
  2921. CLASS="varname"
  2922. >$_POST['name']</VAR
  2923. > and <VAR
  2924. CLASS="varname"
  2925. >$_POST['age']</VAR
  2926. >
  2927.     variables are automatically set for you by PHP.  Earlier we
  2928.     used the <VAR
  2929. CLASS="varname"
  2930. >$_SERVER</VAR
  2931. > autoglobal; above we just 
  2932.     introduced the <A
  2933. HREF="#reserved.variables.post"
  2934. >$_POST</A
  2935. >
  2936.     autoglobal which contains all POST data.  Notice how the
  2937.     <SPAN
  2938. CLASS="emphasis"
  2939. ><I
  2940. CLASS="emphasis"
  2941. >method</I
  2942. ></SPAN
  2943. > of our form is POST.  If we used the 
  2944.     method <SPAN
  2945. CLASS="emphasis"
  2946. ><I
  2947. CLASS="emphasis"
  2948. >GET</I
  2949. ></SPAN
  2950. > then our form information would live in 
  2951.     the <A
  2952. HREF="#reserved.variables.get"
  2953. >$_GET</A
  2954. > autoglobal instead.
  2955.     You may also use the <A
  2956. HREF="#reserved.variables.request"
  2957. >$_REQUEST</A
  2958. >
  2959.     autoglobal, if you do not care about the source of your request data. It 
  2960.     contains the merged information of GET, POST and COOKIE data.  Also see the 
  2961.     <A
  2962. HREF="#function.import-request-variables"
  2963. ><B
  2964. CLASS="function"
  2965. >import_request_variables()</B
  2966. ></A
  2967. > function.
  2968.    </P
  2969. ><P
  2970. >     You can also deal with XForms input in PHP, although you will find yourself
  2971.     comfortable with the well supported HTML forms for quite some time.
  2972.     While working with XForms is not for beginners, you might be interested
  2973.     in them. We also have a <A
  2974. HREF="#features.xforms"
  2975. >short introduction
  2976.     to handling data received from XForms</A
  2977. > in our features section. 
  2978.    </P
  2979. ></DIV
  2980. ><DIV
  2981. CLASS="sect1"
  2982. ><HR><H2
  2983. CLASS="sect1"
  2984. ><A
  2985. NAME="tutorial.oldcode"
  2986. >Using old code with new versions of PHP</A
  2987. ></H2
  2988. ><P
  2989. >     Now that PHP has grown to be a popular scripting language, there are
  2990.     a lot of public repositories and libraries containing code you can reuse.
  2991.     The PHP developers have largely tried to preserve backwards compatibility, 
  2992.     so a script written for an older version will run (ideally) without changes
  2993.     in a newer version of PHP. In practice, some changes will usually be needed.
  2994.    </P
  2995. ><P
  2996. >     Two of the most important recent changes that affect old code are:
  2997.     <P
  2998. ></P
  2999. ><UL
  3000. ><LI
  3001. ><P
  3002. >        The deprecation of the old <VAR
  3003. CLASS="varname"
  3004. >$HTTP_*_VARS</VAR
  3005. > arrays
  3006.        (which need to be indicated as global when used inside a function or
  3007.        method).  The following 
  3008.        <A
  3009. HREF="#language.variables.superglobals"
  3010. >autoglobal arrays</A
  3011. >
  3012.        were introduced in PHP <A
  3013. HREF="http://www.php.net/release_4_1_0.php"
  3014. TARGET="_top"
  3015. >4.1.0</A
  3016. >. 
  3017.        They are: <VAR
  3018. CLASS="varname"
  3019. >$_GET</VAR
  3020. >, <VAR
  3021. CLASS="varname"
  3022. >$_POST</VAR
  3023. >, 
  3024.        <VAR
  3025. CLASS="varname"
  3026. >$_COOKIE</VAR
  3027. >, <VAR
  3028. CLASS="varname"
  3029. >$_SERVER</VAR
  3030. >, 
  3031.        <VAR
  3032. CLASS="varname"
  3033. >$_FILES</VAR
  3034. >, <VAR
  3035. CLASS="varname"
  3036. >$_ENV</VAR
  3037. >,
  3038.        <VAR
  3039. CLASS="varname"
  3040. >$_REQUEST</VAR
  3041. >, and <VAR
  3042. CLASS="varname"
  3043. >$_SESSION</VAR
  3044. >.  The
  3045.        older <VAR
  3046. CLASS="varname"
  3047. >$HTTP_*_VARS</VAR
  3048. > arrays, such as
  3049.        <VAR
  3050. CLASS="varname"
  3051. >$HTTP_POST_VARS</VAR
  3052. >, still exist as they have since PHP 3. 
  3053.        As of PHP 5.0.0, the long PHP 
  3054. <A
  3055. HREF="#language.variables.predefined"
  3056. >predefined variable</A
  3057. >
  3058. arrays may be disabled with the 
  3059. <A
  3060. HREF="#ini.register-long-arrays"
  3061. >register_long_arrays</A
  3062. >
  3063. directive.
  3064.       </P
  3065. ></LI
  3066. ><LI
  3067. ><P
  3068. >        External variables are no longer registered in the global scope by
  3069.        default.  In other words, as of PHP
  3070.        <A
  3071. HREF="http://www.php.net/release_4_2_0.php"
  3072. TARGET="_top"
  3073. >4.2.0</A
  3074. > the PHP directive 
  3075.        <A
  3076. HREF="#ini.register-globals"
  3077. >register_globals</A
  3078. > is 
  3079.        <SPAN
  3080. CLASS="emphasis"
  3081. ><I
  3082. CLASS="emphasis"
  3083. >off</I
  3084. ></SPAN
  3085. > by default in <TT
  3086. CLASS="filename"
  3087. >php.ini</TT
  3088. >. The preferred 
  3089.        method of accessing these values is via the autoglobal arrays mentioned
  3090.        above.  Older scripts, books, and tutorials may rely on this 
  3091.        directive being on.  If it were on, for example, one could use 
  3092.        <VAR
  3093. CLASS="varname"
  3094. >$id</VAR
  3095. > from the URL 
  3096.        <VAR
  3097. CLASS="literal"
  3098. >http://www.example.com/foo.php?id=42</VAR
  3099. >.  Whether on 
  3100.        or off, <VAR
  3101. CLASS="varname"
  3102. >$_GET['id']</VAR
  3103. > is available.
  3104.       </P
  3105. ></LI
  3106. ></UL
  3107. >
  3108.     For more details on these changes, see the section on 
  3109.     <A
  3110. HREF="#language.variables.predefined"
  3111. >predefined variables</A
  3112. >
  3113.     and links therein.
  3114.    </P
  3115. ></DIV
  3116. ><DIV
  3117. CLASS="sect1"
  3118. ><HR><H2
  3119. CLASS="sect1"
  3120. ><A
  3121. NAME="tutorial.whatsnext"
  3122. >What's next?</A
  3123. ></H2
  3124. ><P
  3125. >     With your new knowledge you should be able to understand most of 
  3126.     the manual and also the various example scripts available in the
  3127.     example archives. You can also find other examples on the php.net
  3128.     websites in the links section:
  3129.     <A
  3130. HREF="http://www.php.net/links.php"
  3131. TARGET="_top"
  3132. >http://www.php.net/links.php</A
  3133. >.
  3134.    </P
  3135. ><P
  3136. >     To view various slide presentations that show more of what PHP can do, 
  3137.     see the PHP Conference Material Sites: <A
  3138. HREF="http://conf.php.net/"
  3139. TARGET="_top"
  3140. >     http://conf.php.net/</A
  3141. > and <A
  3142. HREF="http://talks.php.net/"
  3143. TARGET="_top"
  3144. >http://talks.php.net/
  3145.     </A
  3146. >
  3147.    </P
  3148. ></DIV
  3149. ></DIV
  3150. ></DIV
  3151. ><DIV
  3152. CLASS="PART"
  3153. ><A
  3154. NAME="install"
  3155. ></A
  3156. ><DIV
  3157. CLASS="TITLEPAGE"
  3158. ><H1
  3159. CLASS="title"
  3160. >II. Installation and Configuration</H1
  3161. ><DIV
  3162. CLASS="TOC"
  3163. ><DL
  3164. ><DT
  3165. ><B
  3166. >Table of Contents</B
  3167. ></DT
  3168. ><DT
  3169. >3. <A
  3170. HREF="#install.general"
  3171. >General Installation Considerations</A
  3172. ></DT
  3173. ><DT
  3174. >4. <A
  3175. HREF="#install.unix"
  3176. >Installation on Unix systems</A
  3177. ></DT
  3178. ><DT
  3179. >5. <A
  3180. HREF="#install.macosx"
  3181. >Installation on Mac OS X</A
  3182. ></DT
  3183. ><DT
  3184. >6. <A
  3185. HREF="#install.windows"
  3186. >Installation on Windows systems</A
  3187. ></DT
  3188. ><DT
  3189. >7. <A
  3190. HREF="#install.pecl"
  3191. >Installation of PECL extensions</A
  3192. ></DT
  3193. ><DT
  3194. >8. <A
  3195. HREF="#install.problems"
  3196. >Problems?</A
  3197. ></DT
  3198. ><DT
  3199. >9. <A
  3200. HREF="#configuration"
  3201. >Runtime Configuration</A
  3202. ></DT
  3203. ></DL
  3204. ></DIV
  3205. ></DIV
  3206. ><DIV
  3207. CLASS="chapter"
  3208. ><HR><H1
  3209. ><A
  3210. NAME="install.general"
  3211. >Chapter 3. General Installation Considerations</A
  3212. ></H1
  3213. ><P
  3214. >     Before starting the installation, first you need to know what do you
  3215.     want to use PHP for. There are three main fields you
  3216.     can use PHP, as described in the
  3217.     <A
  3218. HREF="#intro-whatcando"
  3219. >What can PHP do?</A
  3220. >
  3221.     section:
  3222.     <P
  3223. ></P
  3224. ><UL
  3225. ><LI
  3226. ><P
  3227. >Server-side scripting</P
  3228. ></LI
  3229. ><LI
  3230. ><P
  3231. >Command line scripting</P
  3232. ></LI
  3233. ><LI
  3234. ><P
  3235. >Client-side GUI applications</P
  3236. ></LI
  3237. ></UL
  3238. >
  3239.    </P
  3240. ><P
  3241. >     For the first and most common form, you need three things:
  3242.     PHP itself, a web server and a web browser. You
  3243.     probably already have a web browser, and depending on
  3244.     your operating system setup, you may also have a web
  3245.     server (e.g. Apache on Linux and MacOS X; IIS on Windows).
  3246.     You may also rent webspace at a company. This way, you
  3247.     don't need to set up anything on your own, only write
  3248.     your PHP scripts, upload it to the server you rent, and
  3249.     see the results in your browser. 
  3250.    </P
  3251. ><P
  3252. >     While setting up the server and PHP on your own, you have
  3253.     two choices for the method of connecting PHP to the
  3254.     server. For many servers PHP has a direct module
  3255.     interface (also called SAPI). These servers include
  3256.     Apache, Microsoft Internet Information Server,
  3257.     Netscape and iPlanet servers. Many other servers
  3258.     have support for ISAPI, the Microsoft module
  3259.     interface (OmniHTTPd for example). If PHP has no
  3260.     module support for your web server, you can always
  3261.     use it as a CGI or FastCGI processor. This means you set up
  3262.     your server to use the CGI executable of
  3263.     PHP to process all PHP file requests on the server.
  3264.    </P
  3265. ><P
  3266. >     If you are also interested to use PHP for command line
  3267.     scripting (e.g. write scripts autogenerating some images
  3268.     for you offline, or processing text files depending
  3269.     on some arguments you pass to them), you always need
  3270.     the command line executable. For more information, read
  3271.     the section about <A
  3272. HREF="#features.commandline"
  3273. >writing
  3274.     command line PHP applications</A
  3275. >. In this case,
  3276.     you need no server and no browser.
  3277.    </P
  3278. ><P
  3279. >     With PHP you can also write desktop GUI applications
  3280.     using the PHP-GTK extension. This is a completely
  3281.     different approach than writing web pages, as you
  3282.     do not output any HTML, but manage windows and objects
  3283.     within them. For more information about PHP-GTK, please
  3284.     <A
  3285. HREF="http://gtk.php.net/"
  3286. TARGET="_top"
  3287. >visit the site dedicated to
  3288.     this extension</A
  3289. >. PHP-GTK is not included in the
  3290.     official PHP distribution.
  3291.    </P
  3292. ><P
  3293. >     From now on, this section deals with setting up PHP
  3294.     for web servers on Unix and Windows with server module
  3295.     interfaces and CGI executables. You will also find
  3296.     information on the command line executable in the
  3297.     following sections.
  3298.    </P
  3299. ><P
  3300. >     PHP source code and binary distributions for Windows can be
  3301.     found at
  3302.     <A
  3303. HREF="http://www.php.net/downloads.php"
  3304. TARGET="_top"
  3305. >http://www.php.net/downloads.php</A
  3306. >.
  3307.     We recommend you to choose a
  3308.     <A
  3309. HREF="http://www.php.net/mirrors.php"
  3310. TARGET="_top"
  3311. >mirror</A
  3312. > nearest
  3313.     to you for downloading the distributions.
  3314.    </P
  3315. ></DIV
  3316. ><DIV
  3317. CLASS="chapter"
  3318. ><HR><H1
  3319. ><A
  3320. NAME="install.unix"
  3321. >Chapter 4. Installation on Unix systems</A
  3322. ></H1
  3323. ><P
  3324. >     This section will guide you through the general configuration and
  3325.     installation of PHP on Unix systems. Be sure to investigate any
  3326.     sections specific to your platform or web server before you begin
  3327.     the process.
  3328.    </P
  3329. ><P
  3330. >     As our manual outlines in the <A
  3331. HREF="#install.general"
  3332. >General
  3333.     Installation Considerations</A
  3334. > section, we are mainly dealing with
  3335.     web centric setups of PHP in this section, although we will cover
  3336.     setting up PHP for command line usage as well.
  3337.    </P
  3338. ><P
  3339. > 
  3340.     There are several ways to install PHP for the Unix platform, either
  3341.     with a compile and configure process, or through various
  3342.     pre-packaged methods. This documentation is mainly focused around
  3343.     the process of compiling and configuring PHP. Many Unix like systems
  3344.     have some sort of package installation system. This can assist in
  3345.     setting up a standard configuration, but if you need to have a
  3346.     different set of features (such as a secure server, or a different
  3347.     database driver), you may need to build PHP and/or your webserver.
  3348.     If you are unfamiliar with building and compiling your own software,
  3349.     it is worth checking to see whether somebody has already built a
  3350.     packaged version of PHP with the features you need.
  3351.    </P
  3352. ><P
  3353. >     Prerequisite knowledge and software for compiling:
  3354.     <P
  3355. ></P
  3356. ><UL
  3357. ><LI
  3358. ><P
  3359. >        Basic Unix skills (being able to operate "make" and a C
  3360.        compiler)
  3361.       </P
  3362. ></LI
  3363. ><LI
  3364. ><P
  3365. >        An ANSI C compiler
  3366.       </P
  3367. ></LI
  3368. ><LI
  3369. ><P
  3370. >        flex: Version 2.5.4
  3371.       </P
  3372. ></LI
  3373. ><LI
  3374. ><P
  3375. >        bison: Version 1.28 (preferred), 1.35, or 1.75
  3376.       </P
  3377. ></LI
  3378. ><LI
  3379. ><P
  3380. >        A web server
  3381.       </P
  3382. ></LI
  3383. ><LI
  3384. ><P
  3385. >        Any module specific components (such as gd, pdf libs, etc.)
  3386.       </P
  3387. ></LI
  3388. ></UL
  3389. >
  3390.    </P
  3391. ><P
  3392. >     The initial PHP setup and configuration process is controlled by the
  3393.     use of the commandline options of the <B
  3394. CLASS="command"
  3395. >configure</B
  3396. >
  3397.     script. You could get a list of all available options along with short
  3398.     explanations running <B
  3399. CLASS="command"
  3400. >./configure --help</B
  3401. >.
  3402.     Our manual documents the different options separately. You will
  3403.     find the <A
  3404. HREF="#configure"
  3405. >core options in the appendix</A
  3406. >,
  3407.     while the different extension specific options are descibed on the
  3408.     reference pages.
  3409.    </P
  3410. ><P
  3411. >     When PHP is configured, you are ready to build the module and/or
  3412.     executables. The command <B
  3413. CLASS="command"
  3414. >make</B
  3415. > should
  3416.     take care of this. If it fails and you can't figure out why, see
  3417.     the <A
  3418. HREF="#install.problems"
  3419. >Problems section</A
  3420. >.
  3421.    </P
  3422. ><DIV
  3423. CLASS="sect1"
  3424. ><HR><H2
  3425. CLASS="sect1"
  3426. ><A
  3427. NAME="install.unix.apache"
  3428. >Apache 1.3.x on Unix systems</A
  3429. ></H2
  3430. ><P
  3431. >      This section contains notes and hints specific to Apache installs
  3432.      of PHP on Unix platforms. We also have <A
  3433. HREF="#install.unix.apache2"
  3434. >instructions and notes for Apache 2
  3435.      on a separate page</A
  3436. >.
  3437.     </P
  3438. ><P
  3439. >      You can select arguments to add to the
  3440.      <B
  3441. CLASS="command"
  3442. >configure</B
  3443. > on line 10 below from the <A
  3444. HREF="#configure"
  3445. >list of core configure options</A
  3446. > and
  3447.      from extension specific options described at the respective
  3448.      places in the manual. The version numbers have been omitted here, to
  3449.      ensure the instructions are not incorrect. You will need to replace
  3450.      the 'xxx' here with the correct values from your files.
  3451.     </P
  3452. ><TABLE
  3453. WIDTH="100%"
  3454. BORDER="0"
  3455. CELLPADDING="0"
  3456. CELLSPACING="0"
  3457. CLASS="EXAMPLE"
  3458. ><TR
  3459. ><TD
  3460. ><DIV
  3461. CLASS="example"
  3462. ><A
  3463. NAME="install.unix.apache.example"
  3464. ></A
  3465. ><P
  3466. ><B
  3467. >Example 4-1. 
  3468.       Installation Instructions (Apache Shared Module Version) for PHP
  3469.      </B
  3470. ></P
  3471. ><TABLE
  3472. BORDER="0"
  3473. BGCOLOR="#E0E0E0"
  3474. CELLPADDING="5"
  3475. ><TR
  3476. ><TD
  3477. ><PRE
  3478. CLASS="screen"
  3479. >1.  gunzip apache_xxx.tar.gz
  3480. 2.  tar -xvf apache_xxx.tar
  3481. 3.  gunzip php-xxx.tar.gz
  3482. 4.  tar -xvf php-xxx.tar
  3483. 5.  cd apache_xxx
  3484. 6.  ./configure --prefix=/www --enable-module=so
  3485. 7.  make
  3486. 8.  make install
  3487. 9.  cd ../php-xxx
  3488.  
  3489. 10. Now, configure your PHP.  This is where you customize your PHP
  3490.     with various options, like which extensions will be enabled.  Do a
  3491.     ./configure --help for a list of available options.  In our example
  3492.     we'll do a simple configure with Apache 1 and MySQL support.  Your
  3493.     path to apxs may differ from our example.
  3494.  
  3495.       ./configure --with-mysql --with-apxs=/www/bin/apxs
  3496.  
  3497. 11. make
  3498. 12. make install
  3499.  
  3500.     If you decide to change your configure options after installation,
  3501.     you only need to repeat the last three steps. You only need to 
  3502.     restart apache for the new module to take effect. A recompile of
  3503.     Apache is not needed.
  3504.   
  3505.     Note that unless told otherwise, 'make install' will also install PEAR,
  3506.     various PHP tools such as phpize, install the PHP CLI, and more.
  3507.  
  3508. 13. Setup your php.ini file:
  3509.  
  3510.       cp php.ini-dist /usr/local/lib/php.ini
  3511.  
  3512.     You may edit your .ini file to set PHP options.  If you prefer your
  3513.     php.ini in another location, use --with-config-file-path=/some/path in
  3514.     step 10. 
  3515.     
  3516.     If you instead choose php.ini-recommended, be certain to read the list
  3517.     of changes within, as they affect how PHP behaves.
  3518.  
  3519. 14. Edit your httpd.conf to load the PHP module.  The path on the right hand
  3520.     side of the LoadModule statement must point to the path of the PHP
  3521.     module on your system.  The make install from above may have already
  3522.     added this for you, but be sure to check.
  3523.         
  3524.     For PHP 4:
  3525.             
  3526.       LoadModule php4_module libexec/libphp4.so
  3527.  
  3528.     For PHP 5:
  3529.                       
  3530.       LoadModule php5_module libexec/libphp5.so
  3531.       
  3532. 15. And in the AddModule section of httpd.conf, somewhere under the
  3533.     ClearModuleList, add this:
  3534.     
  3535.     For PHP 4:
  3536.     
  3537.       AddModule mod_php4.c
  3538.       
  3539.     For PHP 5:
  3540.     
  3541.       AddModule mod_php5.c
  3542.  
  3543. 16. Tell Apache to parse certain extensions as PHP.  For example,
  3544.     let's have Apache parse the .php extension as PHP.  You could
  3545.     have any extension(s) parse as PHP by simply adding more, with
  3546.     each separated by a space.  We'll add .phtml to demonstrate.
  3547.  
  3548.       AddType application/x-httpd-php .php .phtml
  3549.  
  3550.     It's also common to setup the .phps extension to show highlighted PHP
  3551.     source, this can be done with:
  3552.     
  3553.       AddType application/x-httpd-php-source .phps
  3554.  
  3555. 17. Use your normal procedure for starting the Apache server. (You must
  3556.     stop and restart the server, not just cause the server to reload by
  3557.     using a HUP or USR1 signal.)</PRE
  3558. ></TD
  3559. ></TR
  3560. ></TABLE
  3561. ></DIV
  3562. ></TD
  3563. ></TR
  3564. ></TABLE
  3565. ><P
  3566. >      Alternatively, to install PHP as a static object:
  3567.     </P
  3568. ><TABLE
  3569. WIDTH="100%"
  3570. BORDER="0"
  3571. CELLPADDING="0"
  3572. CELLSPACING="0"
  3573. CLASS="EXAMPLE"
  3574. ><TR
  3575. ><TD
  3576. ><DIV
  3577. CLASS="example"
  3578. ><A
  3579. NAME="install.unix.apache.example-static"
  3580. ></A
  3581. ><P
  3582. ><B
  3583. >Example 4-2. 
  3584.       Installation Instructions (Static Module Installation for Apache) for PHP
  3585.      </B
  3586. ></P
  3587. ><TABLE
  3588. BORDER="0"
  3589. BGCOLOR="#E0E0E0"
  3590. CELLPADDING="5"
  3591. ><TR
  3592. ><TD
  3593. ><PRE
  3594. CLASS="screen"
  3595. >1.  gunzip -c apache_1.3.x.tar.gz | tar xf -
  3596. 2.  cd apache_1.3.x
  3597. 3.  ./configure
  3598. 4.  cd ..
  3599.  
  3600. 5.  gunzip -c php-4.x.y.tar.gz | tar xf -
  3601. 6.  cd php-4.x.y
  3602. 7.  ./configure --with-mysql --with-apache=../apache_1.3.x
  3603. 8.  make
  3604. 9.  make install
  3605.  
  3606. 10. cd ../apache_1.3.x
  3607.  
  3608. 11. ./configure --prefix=/www --activate-module=src/modules/php4/libphp4.a
  3609.     (The above line is correct! Yes, we know libphp4.a does not exist at this
  3610.     stage. It isn't supposed to. It will be created.)
  3611.  
  3612. 12. make
  3613.     (you should now have an httpd binary which you can copy to your Apache bin dir if
  3614.     is is your first install then you need to "make install" as well)
  3615.  
  3616. 13. cd ../php-4.x.y
  3617. 14. cp php.ini-dist /usr/local/lib/php.ini
  3618.  
  3619. 15. You can edit /usr/local/lib/php.ini file to set PHP options.
  3620.     Edit your httpd.conf or srm.conf file and add:
  3621.     AddType application/x-httpd-php .php</PRE
  3622. ></TD
  3623. ></TR
  3624. ></TABLE
  3625. ></DIV
  3626. ></TD
  3627. ></TR
  3628. ></TABLE
  3629. ><P
  3630. >       Depending on your Apache install and Unix variant, there are many
  3631.       possible ways to stop and restart the server. Below are some typical
  3632.       lines used in restarting the server, for different apache/unix
  3633.       installations. You should replace <VAR
  3634. CLASS="literal"
  3635. >/path/to/</VAR
  3636. > with
  3637.       the path to these applications on your systems.
  3638.      </P
  3639. ><P
  3640. >       <TABLE
  3641. WIDTH="100%"
  3642. BORDER="0"
  3643. CELLPADDING="0"
  3644. CELLSPACING="0"
  3645. CLASS="EXAMPLE"
  3646. ><TR
  3647. ><TD
  3648. ><DIV
  3649. CLASS="example"
  3650. ><A
  3651. NAME="AEN412"
  3652. ></A
  3653. ><P
  3654. ><B
  3655. >Example 4-3. Example commands for restarting Apache</B
  3656. ></P
  3657. ><TABLE
  3658. BORDER="0"
  3659. BGCOLOR="#E0E0E0"
  3660. CELLPADDING="5"
  3661. ><TR
  3662. ><TD
  3663. ><PRE
  3664. CLASS="shell"
  3665. >1. Several Linux and SysV variants:
  3666. /etc/rc.d/init.d/httpd restart
  3667.  
  3668. 2. Using apachectl scripts:
  3669. /path/to/apachectl stop
  3670. /path/to/apachectl start
  3671.  
  3672. 3. httpdctl and httpsdctl (Using OpenSSL), similar to apachectl:
  3673. /path/to/httpsdctl stop
  3674. /path/to/httpsdctl start
  3675.  
  3676. 4. Using mod_ssl, or another SSL server, you may want to manually
  3677. stop and start:
  3678. /path/to/apachectl stop
  3679. /path/to/apachectl startssl</PRE
  3680. ></TD
  3681. ></TR
  3682. ></TABLE
  3683. ></DIV
  3684. ></TD
  3685. ></TR
  3686. ></TABLE
  3687. >
  3688.      </P
  3689. ><P
  3690. >       The locations of the apachectl and http(s)dctl binaries often
  3691.       vary. If your system has <VAR
  3692. CLASS="literal"
  3693. >locate</VAR
  3694. > or
  3695.       <VAR
  3696. CLASS="literal"
  3697. >whereis</VAR
  3698. > or <VAR
  3699. CLASS="literal"
  3700. >which</VAR
  3701. > commands,
  3702.       these can assist you in finding your server control programs.
  3703.      </P
  3704. ><P
  3705. >       Different examples of compiling PHP for apache are as follows:
  3706.       <DIV
  3707. CLASS="informalexample"
  3708. ><P
  3709. ></P
  3710. ><A
  3711. NAME="AEN420"
  3712. ></A
  3713. ><TABLE
  3714. BORDER="0"
  3715. BGCOLOR="#E0E0E0"
  3716. CELLPADDING="5"
  3717. ><TR
  3718. ><TD
  3719. ><PRE
  3720. CLASS="shell"
  3721. >./configure --with-apxs --with-pgsql</PRE
  3722. ></TD
  3723. ></TR
  3724. ></TABLE
  3725. ><P
  3726. ></P
  3727. ></DIV
  3728. >
  3729.      </P
  3730. ><P
  3731. >       This will create a <TT
  3732. CLASS="filename"
  3733. >libphp4.so</TT
  3734. > shared
  3735.       library that is loaded into Apache using a LoadModule line in
  3736.       Apache's <TT
  3737. CLASS="filename"
  3738. >httpd.conf</TT
  3739. > file. The PostgreSQL
  3740.       support is embedded into this <TT
  3741. CLASS="filename"
  3742. >libphp4.so</TT
  3743. >
  3744.       library.
  3745.      </P
  3746. ><P
  3747. >       <DIV
  3748. CLASS="informalexample"
  3749. ><P
  3750. ></P
  3751. ><A
  3752. NAME="AEN427"
  3753. ></A
  3754. ><TABLE
  3755. BORDER="0"
  3756. BGCOLOR="#E0E0E0"
  3757. CELLPADDING="5"
  3758. ><TR
  3759. ><TD
  3760. ><PRE
  3761. CLASS="shell"
  3762. >./configure --with-apxs --with-pgsql=shared</PRE
  3763. ></TD
  3764. ></TR
  3765. ></TABLE
  3766. ><P
  3767. ></P
  3768. ></DIV
  3769. >
  3770.      </P
  3771. ><P
  3772. >       This will create a <TT
  3773. CLASS="filename"
  3774. >libphp4.so</TT
  3775. > shared
  3776.       library for Apache, but it will also create a
  3777.       <TT
  3778. CLASS="filename"
  3779. >pgsql.so</TT
  3780. > shared library that is loaded into
  3781.       PHP either by using the extension directive in
  3782.       <TT
  3783. CLASS="filename"
  3784. >php.ini</TT
  3785. > file or by loading it explicitly in
  3786.       a script using the <A
  3787. HREF="#function.dl"
  3788. ><B
  3789. CLASS="function"
  3790. >dl()</B
  3791. ></A
  3792. > function.
  3793.      </P
  3794. ><P
  3795. >       <DIV
  3796. CLASS="informalexample"
  3797. ><P
  3798. ></P
  3799. ><A
  3800. NAME="AEN435"
  3801. ></A
  3802. ><TABLE
  3803. BORDER="0"
  3804. BGCOLOR="#E0E0E0"
  3805. CELLPADDING="5"
  3806. ><TR
  3807. ><TD
  3808. ><PRE
  3809. CLASS="shell"
  3810. >./configure --with-apache=/path/to/apache_source --with-pgsql</PRE
  3811. ></TD
  3812. ></TR
  3813. ></TABLE
  3814. ><P
  3815. ></P
  3816. ></DIV
  3817. >
  3818.      </P
  3819. ><P
  3820. >       This will create a <TT
  3821. CLASS="filename"
  3822. >libmodphp4.a</TT
  3823. > library, a
  3824.       <TT
  3825. CLASS="filename"
  3826. >mod_php4.c</TT
  3827. > and some accompanying files and
  3828.       copy this into the <VAR
  3829. CLASS="literal"
  3830. >src/modules/php4</VAR
  3831. > directory
  3832.       in the Apache source tree. Then you compile Apache using
  3833.       <VAR
  3834. CLASS="literal"
  3835. >--activate-module=src/modules/php4/libphp4.a</VAR
  3836. >
  3837.       and the Apache build system will create
  3838.       <TT
  3839. CLASS="filename"
  3840. >libphp4.a</TT
  3841. > and link it statically into the
  3842.       <TT
  3843. CLASS="filename"
  3844. >httpd</TT
  3845. > binary. The PostgreSQL support is
  3846.       included directly into this <TT
  3847. CLASS="filename"
  3848. >httpd</TT
  3849. > binary,
  3850.       so the final result here is a single <TT
  3851. CLASS="filename"
  3852. >httpd</TT
  3853. >
  3854.       binary that includes all of Apache and all of PHP.
  3855.      </P
  3856. ><P
  3857. >       <DIV
  3858. CLASS="informalexample"
  3859. ><P
  3860. ></P
  3861. ><A
  3862. NAME="AEN447"
  3863. ></A
  3864. ><TABLE
  3865. BORDER="0"
  3866. BGCOLOR="#E0E0E0"
  3867. CELLPADDING="5"
  3868. ><TR
  3869. ><TD
  3870. ><PRE
  3871. CLASS="shell"
  3872. >./configure --with-apache=/path/to/apache_source --with-pgsql=shared</PRE
  3873. ></TD
  3874. ></TR
  3875. ></TABLE
  3876. ><P
  3877. ></P
  3878. ></DIV
  3879. >
  3880.      </P
  3881. ><P
  3882. >       Same as before, except instead of including PostgreSQL support
  3883.       directly into the final <TT
  3884. CLASS="filename"
  3885. >httpd</TT
  3886. > you will get
  3887.       a <TT
  3888. CLASS="filename"
  3889. >pgsql.so</TT
  3890. > shared library that you can load
  3891.       into PHP from either the <TT
  3892. CLASS="filename"
  3893. >php.ini</TT
  3894. > file or
  3895.       directly using <A
  3896. HREF="#function.dl"
  3897. ><B
  3898. CLASS="function"
  3899. >dl()</B
  3900. ></A
  3901. >.
  3902.      </P
  3903. ><P
  3904. >       When choosing to build PHP in different ways, you should consider
  3905.       the advantages and drawbacks of each method. Building as a shared
  3906.       object will mean that you can compile apache separately, and don't
  3907.       have to recompile everything as you add to, or change, PHP.
  3908.       Building PHP into apache (static method) means that PHP will
  3909.       load and run faster. For more information, see the Apache
  3910.       <A
  3911. HREF="http://httpd.apache.org/docs/dso.html"
  3912. TARGET="_top"
  3913. >webpage on DSO support</A
  3914. >.
  3915.      </P
  3916. ><DIV
  3917. CLASS="note"
  3918. ><BLOCKQUOTE
  3919. CLASS="note"
  3920. ><P
  3921. ><B
  3922. >Note: </B
  3923. >
  3924.       Apache's default <TT
  3925. CLASS="filename"
  3926. >httpd.conf</TT
  3927. > currently ships with a section that looks
  3928.       like this:
  3929.       <DIV
  3930. CLASS="informalexample"
  3931. ><P
  3932. ></P
  3933. ><A
  3934. NAME="AEN459"
  3935. ></A
  3936. ><TABLE
  3937. BORDER="0"
  3938. BGCOLOR="#E0E0E0"
  3939. CELLPADDING="5"
  3940. ><TR
  3941. ><TD
  3942. ><PRE
  3943. CLASS="apache-conf"
  3944. >User nobody
  3945. Group "#-1"</PRE
  3946. ></TD
  3947. ></TR
  3948. ></TABLE
  3949. ><P
  3950. ></P
  3951. ></DIV
  3952. >
  3953.       Unless you change that to "Group nogroup" or something like that ("Group daemon" is
  3954.       also very common) PHP will not be able to open files.
  3955.      </P
  3956. ></BLOCKQUOTE
  3957. ></DIV
  3958. ><DIV
  3959. CLASS="note"
  3960. ><BLOCKQUOTE
  3961. CLASS="note"
  3962. ><P
  3963. ><B
  3964. >Note: </B
  3965. >
  3966.       Make sure you specify the installed version of apxs when using
  3967.       <VAR
  3968. CLASS="option"
  3969. >--with-apxs=/path/to/apxs</VAR
  3970. >.
  3971.       You must NOT use the apxs version that is in the apache sources but the one
  3972.       that is actually installed on your system.
  3973.      </P
  3974. ></BLOCKQUOTE
  3975. ></DIV
  3976. ></DIV
  3977. ><DIV
  3978. CLASS="sect1"
  3979. ><HR><H2
  3980. CLASS="sect1"
  3981. ><A
  3982. NAME="install.unix.apache2"
  3983. >Apache 2.0 on Unix systems</A
  3984. ></H2
  3985. ><P
  3986. >      This section contains notes and hints specific to Apache 2.0 installs
  3987.      of PHP on Unix systems.
  3988.     </P
  3989. ><DIV
  3990. CLASS="warning"
  3991. ><P
  3992. ></P
  3993. ><TABLE
  3994. CLASS="warning"
  3995. BORDER="1"
  3996. WIDTH="100%"
  3997. ><TR
  3998. ><TD
  3999. ALIGN="CENTER"
  4000. ><B
  4001. >Warning</B
  4002. ></TD
  4003. ></TR
  4004. ><TR
  4005. ><TD
  4006. ALIGN="LEFT"
  4007. ><P
  4008. >We do not recommend using a threaded MPM
  4009. in production with Apache2.  Use the prefork MPM instead, or use Apache1.  For information
  4010. on why, read the following 
  4011. <A
  4012. HREF="#faq.installation.apache2"
  4013. >FAQ entry</A
  4014. ></P
  4015. ></TD
  4016. ></TR
  4017. ></TABLE
  4018. ></DIV
  4019. ><P
  4020. >      You are highly encouraged to take a look at the
  4021.      <A
  4022. HREF="http://httpd.apache.org/docs-2.0/"
  4023. TARGET="_top"
  4024. >Apache Documentation</A
  4025. > to get
  4026.      a basic understanding of the Apache 2.0 Server.
  4027.     </P
  4028. ><DIV
  4029. CLASS="note"
  4030. ><BLOCKQUOTE
  4031. CLASS="note"
  4032. ><P
  4033. ><B
  4034. >PHP and Apache 2.0.x compatibility notes: </B
  4035. >
  4036.       The following versions of PHP are known to work with the most recent
  4037.       version of Apache 2.0.x:
  4038.       <P
  4039. ></P
  4040. ><UL
  4041. COMPACT="COMPACT"
  4042. ><LI
  4043. ><SPAN
  4044. >          PHP 4.3.0 or later available at
  4045.          <A
  4046. HREF="http://www.php.net/downloads.php"
  4047. TARGET="_top"
  4048. >http://www.php.net/downloads.php</A
  4049. >.
  4050.         </SPAN
  4051. ></LI
  4052. ><LI
  4053. ><SPAN
  4054. >          the latest stable development version.
  4055.          Get the source code <A
  4056. HREF="http://snaps.php.net/php4-latest.tar.gz"
  4057. TARGET="_top"
  4058. >          http://snaps.php.net/php4-latest.tar.gz</A
  4059. > or download binaries
  4060.          for Windows <A
  4061. HREF="http://snaps.php.net/win32/php4-win32-latest.zip"
  4062. TARGET="_top"
  4063. >          http://snaps.php.net/win32/php4-win32-latest.zip</A
  4064. >.
  4065.         </SPAN
  4066. ></LI
  4067. ><LI
  4068. ><SPAN
  4069. >          a prerelease version downloadable from
  4070.          <A
  4071. HREF="http://qa.php.net/"
  4072. TARGET="_top"
  4073. >http://qa.php.net/</A
  4074. >.
  4075.         </SPAN
  4076. ></LI
  4077. ><LI
  4078. ><SPAN
  4079. >          you have always the option to obtain PHP through
  4080.          <A
  4081. HREF="http://www.php.net/anoncvs.php"
  4082. TARGET="_top"
  4083. >anonymous CVS</A
  4084. >.
  4085.         </SPAN
  4086. ></LI
  4087. ></UL
  4088. >
  4089.       These versions of PHP are compatible to Apache 2.0.40 and later.
  4090.      </P
  4091. ><P
  4092. >       Apache 2.0 <VAR
  4093. CLASS="literal"
  4094. >SAPI</VAR
  4095. >-support started with PHP 4.2.0.
  4096.       PHP 4.2.3 works with Apache 2.0.39, don't use any other version of Apache with
  4097.       PHP 4.2.3. However, the recommended setup is to use PHP 4.3.0 or later with
  4098.       the most recent version of Apache2.
  4099.      </P
  4100. ><P
  4101. >       All mentioned versions of PHP will work still with
  4102.       Apache 1.3.x.
  4103.      </P
  4104. ></BLOCKQUOTE
  4105. ></DIV
  4106. ><P
  4107. >      Download the most recent version of <A
  4108. HREF="http://www.apache.org/"
  4109. TARGET="_top"
  4110. >      Apache 2.0</A
  4111. > and a fitting PHP version from the above mentioned places.
  4112.      This quick guide covers only the basics to get started with Apache 2.0
  4113.      and PHP. For more information read the
  4114.      <A
  4115. HREF="http://httpd.apache.org/docs-2.0/"
  4116. TARGET="_top"
  4117. >Apache Documentation</A
  4118. >.
  4119.      The version numbers have been omitted here, to ensure the
  4120.      instructions are not incorrect. You will need to replace the
  4121.      'NN' here with the correct values from your files.
  4122.     </P
  4123. ><TABLE
  4124. WIDTH="100%"
  4125. BORDER="0"
  4126. CELLPADDING="0"
  4127. CELLSPACING="0"
  4128. CLASS="EXAMPLE"
  4129. ><TR
  4130. ><TD
  4131. ><DIV
  4132. CLASS="example"
  4133. ><A
  4134. NAME="AEN495"
  4135. ></A
  4136. ><P
  4137. ><B
  4138. >Example 4-4. 
  4139.       Installation Instructions (Apache 2 Shared Module Version)
  4140.      </B
  4141. ></P
  4142. ><TABLE
  4143. BORDER="0"
  4144. BGCOLOR="#E0E0E0"
  4145. CELLPADDING="5"
  4146. ><TR
  4147. ><TD
  4148. ><PRE
  4149. CLASS="screen"
  4150. >1.  gzip -d httpd-2_0_NN.tar.gz
  4151. 2.  tar xvf httpd-2_0_NN.tar
  4152. 3.  gunzip php-NN.tar.gz
  4153. 4.  tar -xvf php-NN.tar
  4154. 5.  cd httpd-2_0_NN
  4155. 6.  ./configure --enable-so
  4156. 7.  make
  4157. 8.  make install
  4158.  
  4159.     Now you have Apache 2.0.NN available under /usr/local/apache2,
  4160.     configured with loadable module support and the standard MPM prefork.
  4161.     To test the installation use your normal procedure for starting
  4162.     the Apache server, e.g.:
  4163.     /usr/local/apache2/bin/apachectl start
  4164.     and stop the server to go on with the configuration for PHP:
  4165.     /usr/local/apache2/bin/apachectl stop.
  4166.  
  4167. 9.  cd ../php-NN
  4168.  
  4169. 10. Now, configure your PHP.  This is where you customize your PHP
  4170.     with various options, like which extensions will be enabled.  Do a
  4171.     ./configure --help for a list of available options.  In our example
  4172.     we'll do a simple configure with Apache 2 and MySQL support.  Your
  4173.     path to apxs may differ, in fact, the binary may even be named apxs2 on
  4174.     your system. 
  4175.     
  4176.       ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql
  4177.  
  4178. 11. make
  4179. 12. make install
  4180.  
  4181.     If you decide to change your configure options after installation,
  4182.     you only need to repeat the last three steps. You only need to
  4183.     restart apache for the new module to take effect. A recompile of
  4184.     Apache is not needed.
  4185.                 
  4186.     Note that unless told otherwise, 'make install' will also install PEAR,
  4187.     various PHP tools such as phpize, install the PHP CLI, and more.
  4188.     
  4189. 13. Setup your php.ini 
  4190.     
  4191.     cp php.ini-dist /usr/local/lib/php.ini
  4192.           
  4193.     You may edit your .ini file to set PHP options.  If you prefer having
  4194.     php.ini in another location, use --with-config-file-path=/some/path in
  4195.     step 10.
  4196.     
  4197.     If you instead choose php.ini-recommended, be certain to read the list
  4198.     of changes within, as they affect how PHP behaves.
  4199.  
  4200. 14. Edit your httpd.conf to load the PHP module.  The path on the right hand
  4201.     side of the LoadModule statement must point to the path of the PHP
  4202.     module on your system.  The make install from above may have already
  4203.     added this for you, but be sure to check.
  4204.  
  4205.     For PHP 4:
  4206.   
  4207.       LoadModule php4_module libexec/libphp4.so
  4208.       
  4209.     For PHP 5:
  4210.     
  4211.       LoadModule php5_module libexec/libphp5.so
  4212.  
  4213. 15. Tell Apache to parse certain extensions as PHP.  For example,
  4214.     let's have Apache parse the .php extension as PHP.  You could
  4215.     have any extension(s) parse as PHP by simply adding more, with
  4216.     each separated by a space.  We'll add .phtml to demonstrate.
  4217.             
  4218.       AddType application/x-httpd-php .php .phtml
  4219.                   
  4220.     It's also common to setup the .phps extension to show highlighted PHP
  4221.     source, this can be done with:
  4222.     
  4223.       AddType application/x-httpd-php-source .phps
  4224.  
  4225. 16. Use your normal procedure for starting the Apache server, e.g.:
  4226.    
  4227.       /usr/local/apache2/bin/apachectl start</PRE
  4228. ></TD
  4229. ></TR
  4230. ></TABLE
  4231. ></DIV
  4232. ></TD
  4233. ></TR
  4234. ></TABLE
  4235. ><P
  4236. >      Following the steps above you will have a running Apache 2.0 with
  4237.      support for PHP as <VAR
  4238. CLASS="literal"
  4239. >SAPI</VAR
  4240. > module.
  4241.      Of course there are many more configuration options available for both,
  4242.      Apache and PHP. For more information use
  4243.      <B
  4244. CLASS="command"
  4245. >./configure --help</B
  4246. > in the corresponding source
  4247.      tree. In case you wish to build a multithreaded version of Apache 2.0
  4248.      you must overwrite the standard MPM-Module <TT
  4249. CLASS="filename"
  4250. >prefork</TT
  4251. >
  4252.      either with <TT
  4253. CLASS="filename"
  4254. >worker</TT
  4255. > or <TT
  4256. CLASS="filename"
  4257. >perchild</TT
  4258. >.
  4259.      To do so append to your configure line in step 6 above either the option
  4260.      <VAR
  4261. CLASS="option"
  4262. >--with-mpm=worker</VAR
  4263. > or
  4264.      <VAR
  4265. CLASS="option"
  4266. >--with-mpm=perchild</VAR
  4267. >. Take care about
  4268.      the consequences and understand what you are doing. For more information
  4269.      read the Apache documentation about the <A
  4270. HREF="http://httpd.apache.org/docs-2.0/mpm.html"
  4271. TARGET="_top"
  4272. >      MPM-Modules</A
  4273. >.
  4274.     </P
  4275. ><DIV
  4276. CLASS="note"
  4277. ><BLOCKQUOTE
  4278. CLASS="note"
  4279. ><P
  4280. ><B
  4281. >Note: </B
  4282. >
  4283.       If you want to use content negotiation, read
  4284.       <A
  4285. HREF="#faq.installation.apache.multiviews"
  4286. >related FAQ</A
  4287. >.
  4288.      </P
  4289. ></BLOCKQUOTE
  4290. ></DIV
  4291. ><DIV
  4292. CLASS="note"
  4293. ><BLOCKQUOTE
  4294. CLASS="note"
  4295. ><P
  4296. ><B
  4297. >Note: </B
  4298. >
  4299.       To build a multithreaded version of Apache your system must support threads.
  4300.       This also implies to build PHP with experimental
  4301.       Zend Thread Safety (ZTS). Therefore not all extensions might be available.
  4302.       The recommended setup is to build Apache with the standard
  4303.       <TT
  4304. CLASS="filename"
  4305. >prefork</TT
  4306. > MPM-Module.
  4307.      </P
  4308. ></BLOCKQUOTE
  4309. ></DIV
  4310. ></DIV
  4311. ><DIV
  4312. CLASS="sect1"
  4313. ><HR><H2
  4314. CLASS="sect1"
  4315. ><A
  4316. NAME="install.unix.caudium"
  4317. >Caudium</A
  4318. ></H2
  4319. ><P
  4320. >     PHP 4 can be built as a Pike module for the
  4321.     <A
  4322. HREF="http://caudium.net/"
  4323. TARGET="_top"
  4324. >Caudium webserver</A
  4325. >.
  4326.     Note that this is not supported with PHP 3. Follow the simple
  4327.     instructions below to install PHP 4 for Caudium.
  4328.    </P
  4329. ><TABLE
  4330. WIDTH="100%"
  4331. BORDER="0"
  4332. CELLPADDING="0"
  4333. CELLSPACING="0"
  4334. CLASS="EXAMPLE"
  4335. ><TR
  4336. ><TD
  4337. ><DIV
  4338. CLASS="example"
  4339. ><A
  4340. NAME="install.unix.caudium.instructions"
  4341. ></A
  4342. ><P
  4343. ><B
  4344. >Example 4-5. Caudium Installation Instructions</B
  4345. ></P
  4346. ><TABLE
  4347. BORDER="0"
  4348. BGCOLOR="#E0E0E0"
  4349. CELLPADDING="5"
  4350. ><TR
  4351. ><TD
  4352. ><PRE
  4353. CLASS="screen"
  4354. >1.  Make sure you have Caudium installed prior to attempting to
  4355.     install PHP 4. For PHP 4 to work correctly, you will need Pike
  4356.     7.0.268 or newer. For the sake of this example we assume that
  4357.     Caudium is installed in /opt/caudium/server/.
  4358. 2.  Change directory to php-x.y.z (where x.y.z is the version number).
  4359. 3.  ./configure --with-caudium=/opt/caudium/server
  4360. 4.  make
  4361. 5.  make install
  4362. 6.  Restart Caudium if it's currently running.
  4363. 7.  Log into the graphical configuration interface and go to the
  4364.     virtual server where you want to add PHP 4 support.
  4365. 8.  Click Add Module and locate and then add the PHP 4 Script Support module.
  4366. 9.  If the documentation says that the 'PHP 4 interpreter isn't
  4367.     available', make sure that you restarted the server. If you did
  4368.     check /opt/caudium/logs/debug/default.1 for any errors related to
  4369.     <filename>PHP4.so</filename>. Also make sure that 
  4370.     <filename>caudium/server/lib/[pike-version]/PHP4.so</filename>
  4371.     is present.
  4372. 10. Configure the PHP Script Support module if needed.</PRE
  4373. ></TD
  4374. ></TR
  4375. ></TABLE
  4376. ></DIV
  4377. ></TD
  4378. ></TR
  4379. ></TABLE
  4380. ><P
  4381. >     You can of course compile your Caudium module with support for the
  4382.     various extensions available in PHP 4. See the reference pages
  4383.     for extension specific configure options.
  4384.    </P
  4385. ><DIV
  4386. CLASS="note"
  4387. ><BLOCKQUOTE
  4388. CLASS="note"
  4389. ><P
  4390. ><B
  4391. >Note: </B
  4392. >
  4393.      When compiling PHP 4 with MySQL support you must make sure that
  4394.      the normal MySQL client code is used. Otherwise there might be
  4395.      conflicts if your Pike already has MySQL support. You do this by
  4396.      specifying a MySQL install directory the 
  4397.      <VAR
  4398. CLASS="option"
  4399. >--with-mysql</VAR
  4400. > option.
  4401.     </P
  4402. ></BLOCKQUOTE
  4403. ></DIV
  4404. ></DIV
  4405. ><DIV
  4406. CLASS="sect1"
  4407. ><HR><H2
  4408. CLASS="sect1"
  4409. ><A
  4410. NAME="install.unix.fhttpd"
  4411. >fhttpd related notes</A
  4412. ></H2
  4413. ><P
  4414. >     To build PHP as an fhttpd module, answer "yes" to "Build as an
  4415.     fhttpd module?" (the <A
  4416. HREF="#configure.with-fhttpd"
  4417. >     --with-fhttpd</A
  4418. >=<VAR
  4419. CLASS="replaceable"
  4420. >DIR</VAR
  4421. >
  4422.     option to configure) and specify the fhttpd source base
  4423.     directory.  The default directory is <TT
  4424. CLASS="filename"
  4425. >/usr/local/src/fhttpd</TT
  4426. >. If you are
  4427.     running fhttpd, building PHP as a module will give better
  4428.     performance, more control and remote execution capability.
  4429.    </P
  4430. ><DIV
  4431. CLASS="note"
  4432. ><BLOCKQUOTE
  4433. CLASS="note"
  4434. ><P
  4435. ><B
  4436. >Note: </B
  4437. >
  4438.      Support for fhttpd is no longer available as of PHP 4.3.0.
  4439.     </P
  4440. ></BLOCKQUOTE
  4441. ></DIV
  4442. ></DIV
  4443. ><DIV
  4444. CLASS="sect1"
  4445. ><HR><H2
  4446. CLASS="sect1"
  4447. ><A
  4448. NAME="install.unix.sun"
  4449. >Sun, iPlanet and Netscape servers on Sun Solaris</A
  4450. ></H2
  4451. ><P
  4452. >      This section contains notes and hints specific to Sun Java System Web Server,
  4453.      Sun ONE Web Server, iPlanet and Netscape server installs of PHP on Sun Solaris.
  4454.     </P
  4455. ><P
  4456. >      From PHP 4.3.3 on you can use PHP scripts with the
  4457.      <A
  4458. HREF="#ref.nsapi"
  4459. >NSAPI module</A
  4460. > to 
  4461.      <A
  4462. HREF="#install.unix.sun.specialpages"
  4463. >generate custom directory
  4464.      listings and error pages</A
  4465. >. Additional functions for Apache
  4466.      compatibility are also available. For support in current webservers read
  4467.      the <A
  4468. HREF="#install.unix.sun.notes"
  4469. >note about subrequests</A
  4470. >.
  4471.     </P
  4472. ><P
  4473. >      You can find more information about setting up PHP for the Netscape
  4474.      Enterprise Server (NES) here:
  4475.      <A
  4476. HREF="http://benoit.noss.free.fr/php/install-php4.html"
  4477. TARGET="_top"
  4478. >http://benoit.noss.free.fr/php/install-php4.html</A
  4479. >
  4480.     </P
  4481. ><P
  4482. >      To build PHP with Sun JSWS/Sun ONE WS/iPlanet/Netscape webservers,
  4483.      enter the proper install directory for the
  4484.      <A
  4485. HREF="#configure.with-nsapi"
  4486. >--with-nsapi=[DIR]</A
  4487. >
  4488.      option. The default directory is usually
  4489.      <TT
  4490. CLASS="filename"
  4491. >/opt/netscape/suitespot/</TT
  4492. >.
  4493.      Please also read <TT
  4494. CLASS="filename"
  4495. >/php-xxx-version/sapi/nsapi/nsapi-readme.txt</TT
  4496. >.
  4497.     </P
  4498. ><P
  4499. >      <P
  4500. ></P
  4501. ><OL
  4502. TYPE="1"
  4503. ><LI
  4504. ><P
  4505. >         Install the following packages from <A
  4506. HREF="http://www.sunfreeware.com/"
  4507. TARGET="_top"
  4508. >         http://www.sunfreeware.com/</A
  4509. > or another download site:
  4510.         <P
  4511. ></P
  4512. ><TABLE
  4513. BORDER="0"
  4514. ><TBODY
  4515. ><TR
  4516. ><TD
  4517. ><TT
  4518. CLASS="filename"
  4519. >autoconf-2.13</TT
  4520. ></TD
  4521. ></TR
  4522. ><TR
  4523. ><TD
  4524. ><TT
  4525. CLASS="filename"
  4526. >automake-1.4</TT
  4527. ></TD
  4528. ></TR
  4529. ><TR
  4530. ><TD
  4531. ><TT
  4532. CLASS="filename"
  4533. >bison-1_25-sol26-sparc-local</TT
  4534. ></TD
  4535. ></TR
  4536. ><TR
  4537. ><TD
  4538. ><TT
  4539. CLASS="filename"
  4540. >flex-2_5_4a-sol26-sparc-local</TT
  4541. ></TD
  4542. ></TR
  4543. ><TR
  4544. ><TD
  4545. ><TT
  4546. CLASS="filename"
  4547. >gcc-2_95_2-sol26-sparc-local</TT
  4548. ></TD
  4549. ></TR
  4550. ><TR
  4551. ><TD
  4552. ><TT
  4553. CLASS="filename"
  4554. >gzip-1.2.4-sol26-sparc-local</TT
  4555. ></TD
  4556. ></TR
  4557. ><TR
  4558. ><TD
  4559. ><TT
  4560. CLASS="filename"
  4561. >m4-1_4-sol26-sparc-local</TT
  4562. ></TD
  4563. ></TR
  4564. ><TR
  4565. ><TD
  4566. ><TT
  4567. CLASS="filename"
  4568. >make-3_76_1-sol26-sparc-local</TT
  4569. ></TD
  4570. ></TR
  4571. ><TR
  4572. ><TD
  4573. >           <TT
  4574. CLASS="filename"
  4575. >mysql-3.23.24-beta</TT
  4576. > (if you want mysql support)
  4577.          </TD
  4578. ></TR
  4579. ><TR
  4580. ><TD
  4581. ><TT
  4582. CLASS="filename"
  4583. >perl-5_005_03-sol26-sparc-local</TT
  4584. ></TD
  4585. ></TR
  4586. ><TR
  4587. ><TD
  4588. ><TT
  4589. CLASS="filename"
  4590. >tar-1.13</TT
  4591. > (GNU tar)</TD
  4592. ></TR
  4593. ></TBODY
  4594. ></TABLE
  4595. ><P
  4596. ></P
  4597. >
  4598.        </P
  4599. ></LI
  4600. ><LI
  4601. ><P
  4602. >         Make sure your path includes the proper directories
  4603.         <VAR
  4604. CLASS="literal"
  4605. >PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin</VAR
  4606. >
  4607.         and make it available to your system <KBD
  4608. CLASS="userinput"
  4609. >export PATH</KBD
  4610. >.
  4611.        </P
  4612. ></LI
  4613. ><LI
  4614. ><P
  4615. >         <KBD
  4616. CLASS="userinput"
  4617. >gunzip php-x.x.x.tar.gz</KBD
  4618. > (if you have a .gz dist,
  4619.         otherwise go to 4).
  4620.        </P
  4621. ></LI
  4622. ><LI
  4623. ><P
  4624. >         <KBD
  4625. CLASS="userinput"
  4626. >tar xvf php-x.x.x.tar</KBD
  4627. >
  4628.        </P
  4629. ></LI
  4630. ><LI
  4631. ><P
  4632. >         Change to your extracted PHP directory:
  4633.         <KBD
  4634. CLASS="userinput"
  4635. >cd ../php-x.x.x </KBD
  4636. >
  4637.        </P
  4638. ></LI
  4639. ><LI
  4640. ><P
  4641. >         For the following step, make sure
  4642.         <TT
  4643. CLASS="filename"
  4644. >/opt/netscape/suitespot/</TT
  4645. > is
  4646.         where your netscape server is installed. Otherwise, change to the
  4647.         correct path and run:
  4648.         <TABLE
  4649. BORDER="0"
  4650. BGCOLOR="#E0E0E0"
  4651. CELLPADDING="5"
  4652. ><TR
  4653. ><TD
  4654. ><PRE
  4655. CLASS="shell"
  4656. >./configure --with-mysql=/usr/local/mysql \
  4657. --with-nsapi=/opt/netscape/suitespot/ \
  4658. --enable-libgcc</PRE
  4659. ></TD
  4660. ></TR
  4661. ></TABLE
  4662. >
  4663.        </P
  4664. ></LI
  4665. ><LI
  4666. ><P
  4667. >         Run <B
  4668. CLASS="command"
  4669. >make</B
  4670. > followed by <B
  4671. CLASS="command"
  4672. >make install</B
  4673. >.
  4674.        </P
  4675. ></LI
  4676. ></OL
  4677. >
  4678.     </P
  4679. ><P
  4680. >      After performing the base install and reading the appropriate readme file,
  4681.      you may need to perform some additional configuration steps.
  4682.     </P
  4683. ><DIV
  4684. CLASS="formalpara"
  4685. ><P
  4686. ><B
  4687. >Configuration Instructions for Sun/iPlanet/Netscape. </B
  4688. >
  4689.       Firstly you may need to add some paths to the <VAR
  4690. CLASS="varname"
  4691. >LD_LIBRARY_PATH</VAR
  4692. >
  4693.       environment for the server to find all the shared libs. This can best done
  4694.       in the start script for your webserver. The start script is often located
  4695.       in: <TT
  4696. CLASS="filename"
  4697. >/path/to/server/https-servername/start</TT
  4698. >.
  4699.       You may also need to edit the configuration files that are
  4700.       located in: <TT
  4701. CLASS="filename"
  4702. >/path/to/server/https-servername/config/</TT
  4703. >.
  4704.       <P
  4705. ></P
  4706. ><OL
  4707. TYPE="1"
  4708. ><LI
  4709. ><P
  4710. >          Add the following line to <TT
  4711. CLASS="filename"
  4712. >mime.types</TT
  4713. > (you can do
  4714.          that by the administration server):
  4715.          <TABLE
  4716. BORDER="0"
  4717. BGCOLOR="#E0E0E0"
  4718. CELLPADDING="5"
  4719. ><TR
  4720. ><TD
  4721. ><PRE
  4722. CLASS="screen"
  4723. >type=magnus-internal/x-httpd-php exts=php</PRE
  4724. ></TD
  4725. ></TR
  4726. ></TABLE
  4727. >
  4728.         </P
  4729. ></LI
  4730. ><LI
  4731. ><P
  4732. >          Edit <TT
  4733. CLASS="filename"
  4734. >magnus.conf</TT
  4735. > (for servers >= 6) or
  4736.          <TT
  4737. CLASS="filename"
  4738. >obj.conf</TT
  4739. > (for servers < 6) and add the following,
  4740.          shlib will vary depending on your system, it will be something like
  4741.          <TT
  4742. CLASS="filename"
  4743. >/opt/netscape/suitespot/bin/libphp4.so</TT
  4744. >. You should
  4745.          place the following lines after <VAR
  4746. CLASS="literal"
  4747. >mime types init</VAR
  4748. >.
  4749.          <TABLE
  4750. BORDER="0"
  4751. BGCOLOR="#E0E0E0"
  4752. CELLPADDING="5"
  4753. ><TR
  4754. ><TD
  4755. ><PRE
  4756. CLASS="programlisting"
  4757. >Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="/opt/netscape/suitespot/bin/libphp4.so"
  4758. Init fn="php4_init" LateInit="yes" errorString="Failed to initialize PHP!" [php_ini="/path/to/php.ini"]</PRE
  4759. ></TD
  4760. ></TR
  4761. ></TABLE
  4762. >
  4763.          (PHP >= 4.3.3) The <VAR
  4764. CLASS="literal"
  4765. >php_ini</VAR
  4766. > parameter is
  4767.          optional but with it you can place your <TT
  4768. CLASS="filename"
  4769. >php.ini</TT
  4770. > in your
  4771.          webserver config directory.
  4772.         </P
  4773. ></LI
  4774. ><LI
  4775. ><P
  4776. >          Configure the default object in <TT
  4777. CLASS="filename"
  4778. >obj.conf</TT
  4779. >
  4780.          (for virtual server classes [version 6.0+] in
  4781.          their <TT
  4782. CLASS="filename"
  4783. >vserver.obj.conf</TT
  4784. >):
  4785.          <TABLE
  4786. BORDER="0"
  4787. BGCOLOR="#E0E0E0"
  4788. CELLPADDING="5"
  4789. ><TR
  4790. ><TD
  4791. ><PRE
  4792. CLASS="programlisting"
  4793. ><Object name="default">
  4794. .
  4795. .
  4796. .
  4797. .#NOTE this next line should happen after all 'ObjectType' and before all 'AddLog' lines
  4798. Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...]
  4799. .
  4800. .
  4801. </Object></PRE
  4802. ></TD
  4803. ></TR
  4804. ></TABLE
  4805. >
  4806.          (PHP >= 4.3.3) As additional parameters you can add some special
  4807.          <TT
  4808. CLASS="filename"
  4809. >php.ini</TT
  4810. >-values, for example you can set a
  4811.          <VAR
  4812. CLASS="literal"
  4813. >docroot="/path/to/docroot"</VAR
  4814. > specific
  4815.          to the context <VAR
  4816. CLASS="literal"
  4817. >php4_execute</VAR
  4818. > is called. For boolean
  4819.          ini-keys please use 0/1 as value, not
  4820.          <VAR
  4821. CLASS="literal"
  4822. >"On","Off",...</VAR
  4823. >
  4824.          (this will not work correctly), e.g.
  4825.          <VAR
  4826. CLASS="literal"
  4827. >zlib.output_compression=1</VAR
  4828. > instead of
  4829.          <VAR
  4830. CLASS="literal"
  4831. >zlib.output_compression="On"</VAR
  4832. >
  4833.         </P
  4834. ></LI
  4835. ><LI
  4836. ><P
  4837. >          This is only needed if you want to configure a directory that only consists of
  4838.          PHP scripts (same like a <TT
  4839. CLASS="filename"
  4840. >cgi-bin</TT
  4841. > directory):
  4842.          <TABLE
  4843. BORDER="0"
  4844. BGCOLOR="#E0E0E0"
  4845. CELLPADDING="5"
  4846. ><TR
  4847. ><TD
  4848. ><PRE
  4849. CLASS="programlisting"
  4850. ><Object name="x-httpd-php">
  4851. ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
  4852. Service fn=php4_execute [inikey=value inikey=value ...]
  4853. </Object></PRE
  4854. ></TD
  4855. ></TR
  4856. ></TABLE
  4857. >
  4858.          After that you can configure a directory in the Administration server and assign it
  4859.          the style <VAR
  4860. CLASS="literal"
  4861. >x-httpd-php</VAR
  4862. >. All files in it will get executed as PHP.
  4863.          This is nice to hide PHP usage by renaming files to <TT
  4864. CLASS="filename"
  4865. >.html</TT
  4866. >.
  4867.         </P
  4868. ></LI
  4869. ><LI
  4870. ><P
  4871. >          Setup of authentication: PHP authentication cannot be used with any
  4872.          other authentication. ALL AUTHENTICATION IS PASSED TO YOUR PHP SCRIPT.
  4873.          To configure PHP Authentication for the entire server, add the
  4874.          following line to your default object:
  4875.          <TABLE
  4876. BORDER="0"
  4877. BGCOLOR="#E0E0E0"
  4878. CELLPADDING="5"
  4879. ><TR
  4880. ><TD
  4881. ><PRE
  4882. CLASS="programlisting"
  4883. ><Object name="default">
  4884. AuthTrans fn=php4_auth_trans
  4885. .
  4886. .
  4887. .
  4888. </Object></PRE
  4889. ></TD
  4890. ></TR
  4891. ></TABLE
  4892. >
  4893.         </P
  4894. ></LI
  4895. ><LI
  4896. ><P
  4897. >          To use PHP Authentication on a single directory, add the following:
  4898.          <TABLE
  4899. BORDER="0"
  4900. BGCOLOR="#E0E0E0"
  4901. CELLPADDING="5"
  4902. ><TR
  4903. ><TD
  4904. ><PRE
  4905. CLASS="programlisting"
  4906. ><Object ppath="d:\path\to\authenticated\dir\*">
  4907. AuthTrans fn=php4_auth_trans
  4908. </Object></PRE
  4909. ></TD
  4910. ></TR
  4911. ></TABLE
  4912. >
  4913.         </P
  4914. ></LI
  4915. ></OL
  4916. >
  4917.      </P
  4918. ></DIV
  4919. ><DIV
  4920. CLASS="note"
  4921. ><BLOCKQUOTE
  4922. CLASS="note"
  4923. ><P
  4924. ><B
  4925. >Note: </B
  4926. >
  4927.       The stacksize that PHP uses depends on the configuration of the webserver. If you get
  4928.       crashes with very large PHP scripts, it is recommended to raise it with the Admin Server
  4929.       (in the section "MAGNUS EDITOR").
  4930.      </P
  4931. ></BLOCKQUOTE
  4932. ></DIV
  4933. ><DIV
  4934. CLASS="sect2"
  4935. ><HR><H3
  4936. CLASS="sect2"
  4937. ><A
  4938. NAME="install.unix.sun.phpini"
  4939. >CGI environment and recommended modifications in php.ini</A
  4940. ></H3
  4941. ><P
  4942. >      Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE
  4943.      WS/iPlanet/Netscape is a multithreaded web server. Because of that all
  4944.      requests are running in the same process space (the space of the webserver
  4945.      itself) and this space has only one environment. If you want to get CGI
  4946.      variables like <VAR
  4947. CLASS="literal"
  4948. >PATH_INFO</VAR
  4949. >, <VAR
  4950. CLASS="literal"
  4951. >HTTP_HOST</VAR
  4952. >
  4953.      etc. it is not the correct way to try this in the old PHP 3.x way with
  4954.      <A
  4955. HREF="#function.getenv"
  4956. ><B
  4957. CLASS="function"
  4958. >getenv()</B
  4959. ></A
  4960. > or a similar way (register globals to
  4961.      environment, <VAR
  4962. CLASS="literal"
  4963. >$_ENV</VAR
  4964. >). You would only get the environment
  4965.      of the running webserver without any valid CGI variables!
  4966.     </P
  4967. ><DIV
  4968. CLASS="note"
  4969. ><BLOCKQUOTE
  4970. CLASS="note"
  4971. ><P
  4972. ><B
  4973. >Note: </B
  4974. >
  4975.       Why are there (invalid) CGI variables in the environment?
  4976.      </P
  4977. ><P
  4978. >       Answer: This is because you started the webserver process from the admin server
  4979.       which runs the startup script of the webserver, you wanted to start, as a CGI script
  4980.       (a CGI script inside of the admin server!). This is why the environment of
  4981.       the started webserver has some CGI environment variables in it. You can test
  4982.       this by starting the webserver not from the administration server. Use
  4983.       the command line as root user and start it manually - you will see
  4984.       there are no CGI-like environment variables.
  4985.      </P
  4986. ></BLOCKQUOTE
  4987. ></DIV
  4988. ><P
  4989. >      Simply change your scripts to get CGI variables in the correct way for
  4990.      PHP 4.x by using the superglobal <VAR
  4991. CLASS="literal"
  4992. >$_SERVER</VAR
  4993. >. If you have
  4994.      older scripts which use <VAR
  4995. CLASS="literal"
  4996. >$HTTP_HOST</VAR
  4997. >, etc., you should turn
  4998.      on <VAR
  4999. CLASS="literal"
  5000. >register_globals</VAR
  5001. > in <TT
  5002. CLASS="filename"
  5003. >php.ini</TT
  5004. > and change the variable
  5005.      order too (important: remove <VAR
  5006. CLASS="literal"
  5007. >"E"</VAR
  5008. > from it,
  5009.      because you do not need the environment here):
  5010.      <TABLE
  5011. BORDER="0"
  5012. BGCOLOR="#E0E0E0"
  5013. CELLPADDING="5"
  5014. ><TR
  5015. ><TD
  5016. ><PRE
  5017. CLASS="programlisting"
  5018. >variables_order = "GPCS"
  5019. register_globals = On</PRE
  5020. ></TD
  5021. ></TR
  5022. ></TABLE
  5023. >
  5024.     </P
  5025. ></DIV
  5026. ><DIV
  5027. CLASS="sect2"
  5028. ><HR><H3
  5029. CLASS="sect2"
  5030. ><A
  5031. NAME="install.unix.sun.specialpages"
  5032. >Special use for error pages or self-made directory listings (PHP >= 4.3.3)</A
  5033. ></H3
  5034. ><P
  5035. >      You can use PHP to generate the error pages for <VAR
  5036. CLASS="literal"
  5037. >"404 Not Found"</VAR
  5038. >
  5039.      or similar. Add the following line to the object in <TT
  5040. CLASS="filename"
  5041. >obj.conf</TT
  5042. > for
  5043.      every error page you want to overwrite:
  5044.      <TABLE
  5045. BORDER="0"
  5046. BGCOLOR="#E0E0E0"
  5047. CELLPADDING="5"
  5048. ><TR
  5049. ><TD
  5050. ><PRE
  5051. CLASS="programlisting"
  5052. >Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]</PRE
  5053. ></TD
  5054. ></TR
  5055. ></TABLE
  5056. >
  5057.      where <VAR
  5058. CLASS="literal"
  5059. >XXX</VAR
  5060. > is the HTTP error code. Please delete
  5061.      any other <VAR
  5062. CLASS="literal"
  5063. >Error</VAR
  5064. > directives which could interfere with yours.
  5065.      If you want to place a page for all errors that could exist, leave
  5066.      the <VAR
  5067. CLASS="literal"
  5068. >code</VAR
  5069. > parameter out. Your script can get the HTTP status code
  5070.      with <VAR
  5071. CLASS="literal"
  5072. >$_SERVER['ERROR_TYPE']</VAR
  5073. >.
  5074.     </P
  5075. ><P
  5076. >      Another possibility is to generate self-made directory listings.
  5077.      Just create a PHP script which displays a directory listing and
  5078.      replace the corresponding default Service line for
  5079.      <VAR
  5080. CLASS="literal"
  5081. >type="magnus-internal/directory"</VAR
  5082. >
  5083.      in <TT
  5084. CLASS="filename"
  5085. >obj.conf</TT
  5086. > with the following:
  5087.      <TABLE
  5088. BORDER="0"
  5089. BGCOLOR="#E0E0E0"
  5090. CELLPADDING="5"
  5091. ><TR
  5092. ><TD
  5093. ><PRE
  5094. CLASS="programlisting"
  5095. >Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]</PRE
  5096. ></TD
  5097. ></TR
  5098. ></TABLE
  5099. >
  5100.      For both error and directory listing pages the original URI and
  5101.      translated URI are in the variables <VAR
  5102. CLASS="literal"
  5103. >$_SERVER['PATH_INFO']</VAR
  5104. > and
  5105.      <VAR
  5106. CLASS="literal"
  5107. >$_SERVER['PATH_TRANSLATED']</VAR
  5108. >.
  5109.     </P
  5110. ></DIV
  5111. ><DIV
  5112. CLASS="sect2"
  5113. ><HR><H3
  5114. CLASS="sect2"
  5115. ><A
  5116. NAME="install.unix.sun.notes"
  5117. >Note about <A
  5118. HREF="#function.nsapi-virtual"
  5119. ><B
  5120. CLASS="function"
  5121. >nsapi_virtual()</B
  5122. ></A
  5123. > and subrequests (PHP >= 4.3.3)</A
  5124. ></H3
  5125. ><P
  5126. >      The NSAPI module now supports the <A
  5127. HREF="#function.nsapi-virtual"
  5128. ><B
  5129. CLASS="function"
  5130. >nsapi_virtual()</B
  5131. ></A
  5132. > function
  5133.      (alias: <A
  5134. HREF="#function.virtual"
  5135. ><B
  5136. CLASS="function"
  5137. >virtual()</B
  5138. ></A
  5139. >)
  5140.      to make subrequests on the webserver and insert the result in the webpage.
  5141.      This function uses some undocumented features from the NSAPI library.
  5142.      On Unix the module automatically looks for the needed functions and uses
  5143.      them if available. If not, <A
  5144. HREF="#function.nsapi-virtual"
  5145. ><B
  5146. CLASS="function"
  5147. >nsapi_virtual()</B
  5148. ></A
  5149. > is disabled.
  5150.     </P
  5151. ><DIV
  5152. CLASS="note"
  5153. ><BLOCKQUOTE
  5154. CLASS="note"
  5155. ><P
  5156. ><B
  5157. >Note: </B
  5158. >
  5159.       But be warned: Support for <A
  5160. HREF="#function.nsapi-virtual"
  5161. ><B
  5162. CLASS="function"
  5163. >nsapi_virtual()</B
  5164. ></A
  5165. > is EXPERIMENTAL!!!
  5166.      </P
  5167. ></BLOCKQUOTE
  5168. ></DIV
  5169. ></DIV
  5170. ></DIV
  5171. ><DIV
  5172. CLASS="sect1"
  5173. ><HR><H2
  5174. CLASS="sect1"
  5175. ><A
  5176. NAME="install.unix.commandline"
  5177. >CGI and commandline setups</A
  5178. ></H2
  5179. ><P
  5180. >     The default is to build PHP as a CGI program.  This creates a
  5181.     commandline interpreter, which can be used for CGI processing, or
  5182.     for non-web-related PHP scripting.  If you are running a web
  5183.     server PHP has module support for, you should generally go for
  5184.     that solution for performance reasons.  However, the CGI version
  5185.     enables users to run different PHP-enabled pages under
  5186.     different user-ids.
  5187.    </P
  5188. ><DIV
  5189. CLASS="warning"
  5190. ><P
  5191. ></P
  5192. ><TABLE
  5193. CLASS="warning"
  5194. BORDER="1"
  5195. WIDTH="100%"
  5196. ><TR
  5197. ><TD
  5198. ALIGN="CENTER"
  5199. ><B
  5200. >Warning</B
  5201. ></TD
  5202. ></TR
  5203. ><TR
  5204. ><TD
  5205. ALIGN="LEFT"
  5206. ><P
  5207. >By using the CGI setup, your server
  5208. is open to several possible attacks. Please read our
  5209. <A
  5210. HREF="#security.cgi-bin"
  5211. >CGI security section</A
  5212. > to learn how to
  5213. defend yourself from those attacks.</P
  5214. ></TD
  5215. ></TR
  5216. ></TABLE
  5217. ></DIV
  5218. ><P
  5219. >     As of PHP 4.3.0, some important additions have happened to PHP.  A new
  5220.     SAPI named CLI also exists and it has the same name as the CGI binary.
  5221.     What is installed at <VAR
  5222. CLASS="literal"
  5223. >{PREFIX}/bin/php</VAR
  5224. > depends on your
  5225.     configure line and this is described in detail in the manual section
  5226.     named <A
  5227. HREF="#features.commandline"
  5228. >Using PHP from the command
  5229.     line</A
  5230. >. For further details please read that section of the manual.
  5231.    </P
  5232. ><DIV
  5233. CLASS="sect2"
  5234. ><HR><H3
  5235. CLASS="sect2"
  5236. ><A
  5237. NAME="install.unix.commandline.testing"
  5238. >Testing</A
  5239. ></H3
  5240. ><P
  5241. >      If you have built PHP as a CGI program, you may test your build
  5242.      by typing <B
  5243. CLASS="command"
  5244. >make test</B
  5245. >.  It is always a good idea
  5246.      to test your build.  This way you may catch a problem with PHP on
  5247.      your platform early instead of having to struggle with it later.
  5248.     </P
  5249. ></DIV
  5250. ><DIV
  5251. CLASS="sect2"
  5252. ><HR><H3
  5253. CLASS="sect2"
  5254. ><A
  5255. NAME="install.unix.commandline.benchmarking"
  5256. >Benchmarking</A
  5257. ></H3
  5258. ><P
  5259. >      If you have built PHP 3 as a CGI program, you may benchmark your
  5260.      build by typing <B
  5261. CLASS="command"
  5262. >make bench</B
  5263. >. Note that if 
  5264.      <A
  5265. HREF="#ini.safe-mode"
  5266. >safe mode</A
  5267. > is on by default, the benchmark may not be able to finish if
  5268.      it takes longer then the 30 seconds allowed. This is because the
  5269.      <A
  5270. HREF="#function.set-time-limit"
  5271. ><B
  5272. CLASS="function"
  5273. >set_time_limit()</B
  5274. ></A
  5275. > can not be used in 
  5276.      <A
  5277. HREF="#ini.safe-mode"
  5278. >safe mode</A
  5279. >. Use the <A
  5280. HREF="#ini.max-execution-time"
  5281. >max_execution_time</A
  5282. >
  5283.      configuration setting to control this time for your own
  5284.      scripts. <B
  5285. CLASS="command"
  5286. >make bench</B
  5287. > ignores the <A
  5288. HREF="#configuration.file"
  5289. >configuration file</A
  5290. >.
  5291.     </P
  5292. ><DIV
  5293. CLASS="note"
  5294. ><BLOCKQUOTE
  5295. CLASS="note"
  5296. ><P
  5297. ><B
  5298. >Note: </B
  5299. >
  5300.         <B
  5301. CLASS="command"
  5302. >make bench</B
  5303. > is only available for PHP 3.
  5304.      </P
  5305. ></BLOCKQUOTE
  5306. ></DIV
  5307. ></DIV
  5308. ><DIV
  5309. CLASS="sect2"
  5310. ><HR><H3
  5311. CLASS="sect2"
  5312. ><A
  5313. NAME="install.unix.commandline.using-variables"
  5314. >Using Variables</A
  5315. ></H3
  5316. ><P
  5317. >       Some <A
  5318. HREF="#reserved.variables.server"
  5319. >server supplied
  5320.       environment variables</A
  5321. > are not defined in the 
  5322.       current <A
  5323. HREF="http://hoohoo.ncsa.uiuc.edu/cgi/env.html"
  5324. TARGET="_top"
  5325. >CGI/1.1 specification</A
  5326. >.
  5327.       Only the following variables are defined there: <VAR
  5328. CLASS="varname"
  5329. >AUTH_TYPE</VAR
  5330. >, 
  5331.       <VAR
  5332. CLASS="varname"
  5333. >CONTENT_LENGTH</VAR
  5334. >, <VAR
  5335. CLASS="varname"
  5336. >CONTENT_TYPE</VAR
  5337. >,
  5338.       <VAR
  5339. CLASS="varname"
  5340. >GATEWAY_INTERFACE</VAR
  5341. >, <VAR
  5342. CLASS="varname"
  5343. >PATH_INFO</VAR
  5344. >, 
  5345.       <VAR
  5346. CLASS="varname"
  5347. >PATH_TRANSLATED</VAR
  5348. >, <VAR
  5349. CLASS="varname"
  5350. >QUERY_STRING</VAR
  5351. >,
  5352.       <VAR
  5353. CLASS="varname"
  5354. >REMOTE_ADDR</VAR
  5355. >, <VAR
  5356. CLASS="varname"
  5357. >REMOTE_HOST</VAR
  5358. >, 
  5359.       <VAR
  5360. CLASS="varname"
  5361. >REMOTE_IDENT</VAR
  5362. >, <VAR
  5363. CLASS="varname"
  5364. >REMOTE_USER</VAR
  5365. >,
  5366.       <VAR
  5367. CLASS="varname"
  5368. >REQUEST_METHOD</VAR
  5369. >, <VAR
  5370. CLASS="varname"
  5371. >SCRIPT_NAME</VAR
  5372. >, 
  5373.       <VAR
  5374. CLASS="varname"
  5375. >SERVER_NAME</VAR
  5376. >, <VAR
  5377. CLASS="varname"
  5378. >SERVER_PORT</VAR
  5379. >,
  5380.       <VAR
  5381. CLASS="varname"
  5382. >SERVER_PROTOCOL</VAR
  5383. >, and <VAR
  5384. CLASS="varname"
  5385. >SERVER_SOFTWARE</VAR
  5386. >.
  5387.       Everything else should be treated as 'vendor extensions'.
  5388.     </P
  5389. ></DIV
  5390. ></DIV
  5391. ><DIV
  5392. CLASS="sect1"
  5393. ><HR><H2
  5394. CLASS="sect1"
  5395. ><A
  5396. NAME="install.unix.hpux"
  5397. >HP-UX specific installation notes</A
  5398. ></H2
  5399. ><P
  5400. >     This section contains notes and hints specific to installing PHP
  5401.     on HP-UX systems. (Contributed by paul_mckay at clearwater-it dot co dot
  5402.     uk).
  5403.    </P
  5404. ><DIV
  5405. CLASS="note"
  5406. ><BLOCKQUOTE
  5407. CLASS="note"
  5408. ><P
  5409. ><B
  5410. >Note: </B
  5411. >
  5412.      These tips were written for PHP 4.0.4 and Apache 1.3.9.
  5413.     </P
  5414. ></BLOCKQUOTE
  5415. ></DIV
  5416. ><P
  5417. >     <P
  5418. ></P
  5419. ><OL
  5420. TYPE="1"
  5421. ><LI
  5422. ><P
  5423. >        You need gzip, download a binary distribution from
  5424.        <TT
  5425. CLASS="filename"
  5426. >http://hpux.connect.org.uk/ftp/hpux/Gnu/gzip-1.2.4a/gzip-1.2.4a-sd-10.20.depot.Z</TT
  5427. >
  5428.        uncompress the file and install using swinstall.
  5429.       </P
  5430. ></LI
  5431. ><LI
  5432. ><P
  5433. >        You need gcc, download a binary distribution from
  5434.        <TT
  5435. CLASS="filename"
  5436. >http://gatekeep.cs.utah.edu/ftp/hpux/Gnu/gcc-2.95.2/gcc-2.95.2-sd-10.20.depot.gz</TT
  5437. >.
  5438.        uncompress this file and install gcc using swinstall.
  5439.       </P
  5440. ></LI
  5441. ><LI
  5442. ><P
  5443. >        You need the GNU binutils, you can download a binary distribution from
  5444.        <TT
  5445. CLASS="filename"
  5446. >http://hpux.connect.org.uk/ftp/hpux/Gnu/binutils-2.9.1/binutils-2.9.1-sd-10.20.depot.gz</TT
  5447. >.
  5448.        uncompress this file and install binutils using swinstall.
  5449.       </P
  5450. ></LI
  5451. ><LI
  5452. ><P
  5453. >        You now need bison, you can download a binary distribution from
  5454.        <TT
  5455. CLASS="filename"
  5456. >http://hpux.connect.org.uk/ftp/hpux/Gnu/bison-1.28/bison-1.28-sd-10.20.depot.gz</TT
  5457. >,
  5458.        install as above.
  5459.       </P
  5460. ></LI
  5461. ><LI
  5462. ><P
  5463. >        You now need flex, you need to download the source from one of the
  5464.        http://www.gnu.org mirrors. It is in the non-gnu directory of the ftp
  5465.        site.  Download the file, <B
  5466. CLASS="command"
  5467. >gunzip</B
  5468. >, then
  5469.        <B
  5470. CLASS="command"
  5471. >tar -xvf</B
  5472. > it. Go into the newly created flex directory
  5473.        and run <B
  5474. CLASS="command"
  5475. >./configure</B
  5476. >, followed by 
  5477.        <B
  5478. CLASS="command"
  5479. >make</B
  5480. >, and then <B
  5481. CLASS="command"
  5482. >make install</B
  5483. >.
  5484.       </P
  5485. ><P
  5486. >        If you have errors here, it's probably because gcc etc. are not in your
  5487.        PATH so add them to your PATH. 
  5488.       </P
  5489. ></LI
  5490. ><LI
  5491. ><P
  5492. >        Download the PHP and apache sources. 
  5493.       </P
  5494. ></LI
  5495. ><LI
  5496. ><P
  5497. >        <B
  5498. CLASS="command"
  5499. >gunzip</B
  5500. > and <B
  5501. CLASS="command"
  5502. >tar -xvf</B
  5503. > them. We
  5504.        need to hack a couple of files so that they can compile OK.
  5505.       </P
  5506. ></LI
  5507. ><LI
  5508. ><P
  5509. >        Firstly the configure file needs to be hacked because it seems to lose
  5510.        track of the fact that you are a hpux machine, there will be a better
  5511.        way of doing this but a cheap and cheerful hack is to put
  5512.        <VAR
  5513. CLASS="literal"
  5514. >lt_target=hpux10.20</VAR
  5515. > on line 47286 of the configure
  5516.        script.
  5517.       </P
  5518. ></LI
  5519. ><LI
  5520. ><P
  5521. >        Next, the Apache GuessOS file needs to be hacked. Under
  5522.        <TT
  5523. CLASS="filename"
  5524. >apache_1.3.9/src/helpers</TT
  5525. > change line 89 from <VAR
  5526. CLASS="literal"
  5527. >echo
  5528.        "hp${HPUXMACH}-hpux${HPUXVER}"; exit 0</VAR
  5529. > to: <VAR
  5530. CLASS="literal"
  5531. >echo
  5532.        "hp${HPUXMACH}-hp-hpux${HPUXVER}"; exit 0</VAR
  5533. >
  5534.       </P
  5535. ></LI
  5536. ><LI
  5537. ><P
  5538. >        You cannot install PHP as a shared object under HP-UX so you must
  5539.        compile it as a static, just follow the instructions at the Apache
  5540.        page. 
  5541.       </P
  5542. ></LI
  5543. ><LI
  5544. ><P
  5545. >        PHP and Apache should have compiled OK, but Apache won't start. you
  5546.        need to create a new user for Apache, e.g. www, or apache. You then
  5547.        change lines 252 and 253 of the <TT
  5548. CLASS="filename"
  5549. >conf/httpd.conf</TT
  5550. > in
  5551.        Apache so that instead of
  5552.       </P
  5553. ><TABLE
  5554. BORDER="0"
  5555. BGCOLOR="#E0E0E0"
  5556. CELLPADDING="5"
  5557. ><TR
  5558. ><TD
  5559. ><PRE
  5560. CLASS="screen"
  5561. >User nobody 
  5562. Group nogroup</PRE
  5563. ></TD
  5564. ></TR
  5565. ></TABLE
  5566. ><P
  5567. >        you have something like 
  5568.       </P
  5569. ><TABLE
  5570. BORDER="0"
  5571. BGCOLOR="#E0E0E0"
  5572. CELLPADDING="5"
  5573. ><TR
  5574. ><TD
  5575. ><PRE
  5576. CLASS="screen"
  5577. >User www 
  5578. Group sys</PRE
  5579. ></TD
  5580. ></TR
  5581. ></TABLE
  5582. ><P
  5583. >        This is because you can't run Apache as nobody under hp-ux. Apache and
  5584.        PHP should then work. 
  5585.       </P
  5586. ></LI
  5587. ></OL
  5588. >
  5589.  </P
  5590. ></DIV
  5591. ><DIV
  5592. CLASS="sect1"
  5593. ><HR><H2
  5594. CLASS="sect1"
  5595. ><A
  5596. NAME="install.unix.openbsd"
  5597. >OpenBSD installation notes</A
  5598. ></H2
  5599. ><P
  5600. >  This section contains notes and hints specific to installing
  5601.  PHP on <A
  5602. HREF="http://www.openbsd.org/"
  5603. TARGET="_top"
  5604. >OpenBSD 3.6</A
  5605. >.
  5606.  </P
  5607. ><DIV
  5608. CLASS="sect2"
  5609. ><HR><H3
  5610. CLASS="sect2"
  5611. ><A
  5612. NAME="install.unix.openbsd.packages"
  5613. >Using Binary Packages</A
  5614. ></H3
  5615. ><P
  5616. >     Using binary packages to install PHP on OpenBSD is the recommended
  5617.     and simplest method.  The core package has been separated from the various
  5618.     modules, and each can be installed and removed independently from the others.
  5619.     The files you need can be found on your OpenBSD CD or on the FTP site.
  5620.    </P
  5621. ><P
  5622. >     The main package you need to install is <TT
  5623. CLASS="filename"
  5624. >php4-core-4.3.8.tgz</TT
  5625. >,
  5626.     which contains the basic engine (plus gettext and iconv).  Next, take a look
  5627.     at the module packages, such as <TT
  5628. CLASS="filename"
  5629. >php4-mysql-4.3.8.tgz</TT
  5630. >
  5631.     or <TT
  5632. CLASS="filename"
  5633. >php4-imap-4.3.8.tgz</TT
  5634. >.  You need to use the <B
  5635. CLASS="command"
  5636. >phpxs</B
  5637. >
  5638.     command to activate and deactivate these modules in your <TT
  5639. CLASS="filename"
  5640. >php.ini</TT
  5641. >.
  5642.    </P
  5643. ><TABLE
  5644. WIDTH="100%"
  5645. BORDER="0"
  5646. CELLPADDING="0"
  5647. CELLSPACING="0"
  5648. CLASS="EXAMPLE"
  5649. ><TR
  5650. ><TD
  5651. ><DIV
  5652. CLASS="example"
  5653. ><A
  5654. NAME="install.unix.openbsd.ports.example"
  5655. ></A
  5656. ><P
  5657. ><B
  5658. >Example 4-6. OpenBSD Package Install Example</B
  5659. ></P
  5660. ><TABLE
  5661. BORDER="0"
  5662. BGCOLOR="#E0E0E0"
  5663. CELLPADDING="5"
  5664. ><TR
  5665. ><TD
  5666. ><PRE
  5667. CLASS="shell"
  5668. ># pkg_add php4-core-4.3.8.tgz
  5669. # /usr/local/sbin/phpxs -s
  5670. # cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini
  5671.   (add in mysql)
  5672. # pkg_add php4-mysql-4.3.8.tgz
  5673. # /usr/local/sbin/phpxs -a mysql
  5674.   (add in imap)
  5675. # pkg_add php4-imap-4.3.8.tgz
  5676. # /usr/local/sbin/phpxs -a imap
  5677.   (remove mysql as a test)
  5678. # pkg_delete php4-mysql-4.3.8
  5679. # /usr/local/sbin/phpxs -r mysql
  5680.   (install the PEAR libraries)
  5681. # pkg_add php4-pear-4.3.8.tgz</PRE
  5682. ></TD
  5683. ></TR
  5684. ></TABLE
  5685. ></DIV
  5686. ></TD
  5687. ></TR
  5688. ></TABLE
  5689. ><P
  5690. >    Read the <A
  5691. HREF="http://www.openbsd.org/cgi-bin/man.cgi?query=packages"
  5692. TARGET="_top"
  5693. >packages(7)</A
  5694. >
  5695.    manual page for more information about binary packages on OpenBSD.
  5696.    </P
  5697. ></DIV
  5698. ><DIV
  5699. CLASS="sect2"
  5700. ><HR><H3
  5701. CLASS="sect2"
  5702. ><A
  5703. NAME="install.unix.openbsd.ports"
  5704. >Using Ports</A
  5705. ></H3
  5706. ><P
  5707. >    You can also compile up PHP from source using the <A
  5708. HREF="http://www.openbsd.org/ports.html"
  5709. TARGET="_top"
  5710. >ports tree</A
  5711. >.
  5712.    However, this is only recommended for users familiar with OpenBSD.  The PHP 4 port
  5713.    is split into two sub-directories: core and extensions.  The
  5714.    extensions directory generates sub-packages for all of the supported
  5715.    PHP modules.  If you find you do not want to create some of these modules,
  5716.    use the <B
  5717. CLASS="command"
  5718. >no_*</B
  5719. > FLAVOR.  For example, to skip building
  5720.    the imap module, set the FLAVOR to <B
  5721. CLASS="command"
  5722. >no_imap</B
  5723. >.
  5724.   </P
  5725. ></DIV
  5726. ><DIV
  5727. CLASS="sect2"
  5728. ><HR><H3
  5729. CLASS="sect2"
  5730. ><A
  5731. NAME="install.unix.openbsd.faq"
  5732. >Common Problems</A
  5733. ></H3
  5734. ><P
  5735. ></P
  5736. ><UL
  5737. ><LI
  5738. ><P
  5739. >The default install of Apache runs inside a
  5740.     <A
  5741. HREF="http://www.openbsd.org/cgi-bin/man.cgi?query=chroot"
  5742. TARGET="_top"
  5743. >chroot(2) jail</A
  5744. >, which will restrict PHP scripts to
  5745.     accessing files under <TT
  5746. CLASS="filename"
  5747. >/var/www</TT
  5748. >.  You will therefore need to create a
  5749.     <TT
  5750. CLASS="filename"
  5751. >/var/www/tmp</TT
  5752. > directory for PHP session files to be stored, or use an
  5753.     alternative session backend.  In addition, database sockets need to be placed inside the
  5754.     jail or listen on the <TT
  5755. CLASS="filename"
  5756. >localhost</TT
  5757. > interface.  If you use network functions,
  5758.     some files from <TT
  5759. CLASS="filename"
  5760. >/etc</TT
  5761. > such as <TT
  5762. CLASS="filename"
  5763. >/etc/resolv.conf</TT
  5764. > and
  5765.     <TT
  5766. CLASS="filename"
  5767. >/etc/services</TT
  5768. > will need to be moved into <TT
  5769. CLASS="filename"
  5770. >/var/www/etc</TT
  5771. >.
  5772.     The OpenBSD PEAR package automatically installs into the correct chroot directories, so 
  5773.     no special modification is needed there.  More information on the OpenBSD Apache is available
  5774.     in the <A
  5775. HREF="http://www.openbsd.org/faq/faq10.html#httpdchroot"
  5776. TARGET="_top"
  5777. >OpenBSD FAQ</A
  5778. >.
  5779.     </P
  5780. ></LI
  5781. ><LI
  5782. ><P
  5783. >     The OpenBSD 3.6 package for the <A
  5784. HREF="http://www.boutell.com/gd/"
  5785. TARGET="_top"
  5786. >gd</A
  5787. > extension requires
  5788.     XFree86 to be installed.  If you do not wish to use some of the font features that
  5789.     require X11, install the <TT
  5790. CLASS="filename"
  5791. >php4-gd-4.3.8-no_x11.tgz</TT
  5792. > package instead.
  5793.     </P
  5794. ></LI
  5795. ></UL
  5796. ></DIV
  5797. ><DIV
  5798. CLASS="sect2"
  5799. ><HR><H3
  5800. CLASS="sect2"
  5801. ><A
  5802. NAME="install.unix.openbsd.older"
  5803. >Older Releases</A
  5804. ></H3
  5805. ><P
  5806. >    Older releases of OpenBSD used the FLAVORS system to compile up
  5807.    a statically linked PHP.  Since it is hard to generate binary packages using
  5808.    this method, it is now deprecated.  You can still use the old stable
  5809.    ports trees if you wish, but they are unsupported by the OpenBSD team.
  5810.    If you have any comments about this, the current maintainer for the port
  5811.    is Anil Madhavapeddy (avsm at openbsd dot org).
  5812.   </P
  5813. ></DIV
  5814. ></DIV
  5815. ><DIV
  5816. CLASS="sect1"
  5817. ><HR><H2
  5818. CLASS="sect1"
  5819. ><A
  5820. NAME="install.unix.solaris"
  5821. >Solaris specific installation tips</A
  5822. ></H2
  5823. ><P
  5824. >   This section contains notes and hints specific to installing
  5825.   PHP on Solaris systems.
  5826.  </P
  5827. ><DIV
  5828. CLASS="sect2"
  5829. ><HR><H3
  5830. CLASS="sect2"
  5831. ><A
  5832. NAME="install.unix.solaris.required"
  5833. >Required software</A
  5834. ></H3
  5835. ><P
  5836. >    Solaris installs often lack C compilers and their related tools.
  5837.    Read <A
  5838. HREF="#faq.installation.needgnu"
  5839. >this FAQ</A
  5840. > 
  5841.    for information on why using GNU versions for some of these
  5842.    tools is necessary.  The required software is as follows:
  5843.    <P
  5844. ></P
  5845. ><UL
  5846. ><LI
  5847. ><P
  5848. >       gcc (recommended, other C compilers may work)
  5849.      </P
  5850. ></LI
  5851. ><LI
  5852. ><P
  5853. >       make
  5854.      </P
  5855. ></LI
  5856. ><LI
  5857. ><P
  5858. >       flex
  5859.      </P
  5860. ></LI
  5861. ><LI
  5862. ><P
  5863. >       bison
  5864.      </P
  5865. ></LI
  5866. ><LI
  5867. ><P
  5868. >       m4
  5869.      </P
  5870. ></LI
  5871. ><LI
  5872. ><P
  5873. >       autoconf
  5874.      </P
  5875. ></LI
  5876. ><LI
  5877. ><P
  5878. >       automake
  5879.      </P
  5880. ></LI
  5881. ><LI
  5882. ><P
  5883. >       perl
  5884.      </P
  5885. ></LI
  5886. ><LI
  5887. ><P
  5888. >       gzip
  5889.      </P
  5890. ></LI
  5891. ><LI
  5892. ><P
  5893. >       tar
  5894.      </P
  5895. ></LI
  5896. ><LI
  5897. ><P
  5898. >       GNU sed
  5899.      </P
  5900. ></LI
  5901. ></UL
  5902. >
  5903.     In addition, you will need to install (and possibly compile) any
  5904.     additional software specific to your configuration, such as Oracle
  5905.     or MySQL.
  5906.   </P
  5907. ></DIV
  5908. ><DIV
  5909. CLASS="sect2"
  5910. ><HR><H3
  5911. CLASS="sect2"
  5912. ><A
  5913. NAME="install.unix.solaris.packages"
  5914. >Using Packages</A
  5915. ></H3
  5916. ><P
  5917. >    You can simplify the Solaris install process by using pkgadd to
  5918.    install most of your needed components. 
  5919.   </P
  5920. ></DIV
  5921. ></DIV
  5922. ><DIV
  5923. CLASS="sect1"
  5924. ><HR><H2
  5925. CLASS="sect1"
  5926. ><A
  5927. NAME="install.unix.gentoo"
  5928. >Gentoo installation notes</A
  5929. ></H2
  5930. ><P
  5931. >   This section contains notes and hints specific to installing
  5932.   PHP on <A
  5933. HREF="http://www.gentoo.org/"
  5934. TARGET="_top"
  5935. >Gentoo Linux</A
  5936. >.
  5937.  </P
  5938. ><DIV
  5939. CLASS="sect2"
  5940. ><HR><H3
  5941. CLASS="sect2"
  5942. ><A
  5943. NAME="install.unix.gentoo.portage"
  5944. >Using Portage (emerge)</A
  5945. ></H3
  5946. ><P
  5947. >     While you can just download the PHP source and compile it yourself,
  5948.     using Gentoo's packaging system is the simplest and cleanest
  5949.     method of installing PHP. If you are not familiar with building
  5950.     software on Linux, this is the way to go.
  5951.    </P
  5952. ><P
  5953. >     If you have built your Gentoo system so far, you are probably used
  5954.     to Portage already. Installing Apache and PHP is no different than 
  5955.     the other system tools.
  5956.    </P
  5957. ><P
  5958. >     The first decision you need to make is whether you want to install
  5959.     Apache 1.3.x or Apache 2.x. While both can be used with PHP, the 
  5960.     steps given bellow will use Apache 1.3.x. Another thing to consider
  5961.     is whether your local Portage tree is up to date. If you have not
  5962.     updated it recently, you need to run <B
  5963. CLASS="command"
  5964. >emerge sync</B
  5965. >
  5966.     before anything else. This way, you will be using the most recent
  5967.     stable version of Apache and PHP.
  5968.    </P
  5969. ><P
  5970. >     Now that everything is in place, you can use the following example
  5971.     to install Apache and PHP:
  5972.    </P
  5973. ><TABLE
  5974. WIDTH="100%"
  5975. BORDER="0"
  5976. CELLPADDING="0"
  5977. CELLSPACING="0"
  5978. CLASS="EXAMPLE"
  5979. ><TR
  5980. ><TD
  5981. ><DIV
  5982. CLASS="example"
  5983. ><A
  5984. NAME="install.unix.gentoo.portage.example"
  5985. ></A
  5986. ><P
  5987. ><B
  5988. >Example 4-7. Gentoo Install Example with Apache 1.3</B
  5989. ></P
  5990. ><TABLE
  5991. BORDER="0"
  5992. BGCOLOR="#E0E0E0"
  5993. CELLPADDING="5"
  5994. ><TR
  5995. ><TD
  5996. ><PRE
  5997. CLASS="shell"
  5998. ># emerge \<apache-2
  5999. # USE="-*" emerge php mod_php
  6000. # ebuild /var/db/pkg/dev-php/mod_php-<your PHP version>/mod_php-<your PHP version>.ebuild config
  6001. # nano /etc/conf.d/apache
  6002.   Add "-D PHP4" to APACHE_OPTS
  6003.   
  6004. # rc-update add apache default
  6005. # /etc/init.d/apache start</PRE
  6006. ></TD
  6007. ></TR
  6008. ></TABLE
  6009. ></DIV
  6010. ></TD
  6011. ></TR
  6012. ></TABLE
  6013. ><P
  6014. >     You can read more about emerge in the excellent 
  6015.     <A
  6016. HREF="http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=1"
  6017. TARGET="_top"
  6018. >Portage Manual</A
  6019. > provided
  6020.     on the Gentoo website.
  6021.    </P
  6022. ><P
  6023. >     If you need to use Apache 2, you can simply use <B
  6024. CLASS="command"
  6025. >emerge apache</B
  6026. >
  6027.     in the last example.
  6028.    </P
  6029. ></DIV
  6030. ><DIV
  6031. CLASS="sect2"
  6032. ><HR><H3
  6033. CLASS="sect2"
  6034. ><A
  6035. NAME="install.unix.gentoo.config"
  6036. >Better control on configuration</A
  6037. ></H3
  6038. ><P
  6039. >     In the last section, PHP was emerged without any activated modules.
  6040.     As of this writing, the only module activated by default with Portage 
  6041.     is XML which is needed by <A
  6042. HREF="http://pear.php.net/"
  6043. TARGET="_top"
  6044. >PEAR</A
  6045. >.
  6046.     This may not be what you want and you will soon discover that you need 
  6047.     more activated modules, like MySQL, gettext, GD, etc.
  6048.    </P
  6049. ><P
  6050. >     When you compile PHP from source yourself, you need to activate modules
  6051.     via the <B
  6052. CLASS="command"
  6053. >configure</B
  6054. > command. With Gentoo, you can simply
  6055.     provide USE flags which will be passed to the configure script automatically.
  6056.     To see which USE flags to use with emerge, you can try:
  6057.    </P
  6058. ><TABLE
  6059. WIDTH="100%"
  6060. BORDER="0"
  6061. CELLPADDING="0"
  6062. CELLSPACING="0"
  6063. CLASS="EXAMPLE"
  6064. ><TR
  6065. ><TD
  6066. ><DIV
  6067. CLASS="example"
  6068. ><A
  6069. NAME="install.unix.gentoo.config.example"
  6070. ></A
  6071. ><P
  6072. ><B
  6073. >Example 4-8. Getting the list of valid USE flags</B
  6074. ></P
  6075. ><TABLE
  6076. BORDER="0"
  6077. BGCOLOR="#E0E0E0"
  6078. CELLPADDING="5"
  6079. ><TR
  6080. ><TD
  6081. ><PRE
  6082. CLASS="shell"
  6083. ># USE="-*" emerge -pv php
  6084.  
  6085. [ebuild  N    ] dev-php/php-4.3.6-r1  -X -berkdb -crypt -curl -debug -doc 
  6086. -fdftk -firebird -flash -freetds -gd -gd-external -gdbm -gmp -hardenedphp 
  6087. -imap -informix -ipv6 -java -jpeg -kerberos -ldap -mcal -memlimit -mssql 
  6088. -mysql -ncurses -nls -oci8 -odbc -pam -pdflib -png -postgres -qt -readline 
  6089. -snmp -spell -ssl -tiff -truetype -xml2 -yaz  3,876 kB</PRE
  6090. ></TD
  6091. ></TR
  6092. ></TABLE
  6093. ></DIV
  6094. ></TD
  6095. ></TR
  6096. ></TABLE
  6097. ><P
  6098. >     As you can see from the last output, PHP considers a lot of USE flags.
  6099.     Look at them closely and choose what you need. If you choose a flag and 
  6100.     you do not have the proper libraries, Portage will compile them for you.
  6101.     It is a good idea to use <B
  6102. CLASS="command"
  6103. >emerge -pv</B
  6104. > again to see what
  6105.     Portage will compile in accordance to your USE flags. As an example,
  6106.     if you do not have X installed and you choose to include X in the USE
  6107.     flags, Portage will compile X prior to PHP, which can take a couple
  6108.     of hours.
  6109.    </P
  6110. ><P
  6111. >     If you choose to compile PHP with MySQL, cURL and GD support, the command
  6112.     will look something like this:
  6113.    </P
  6114. ><TABLE
  6115. WIDTH="100%"
  6116. BORDER="0"
  6117. CELLPADDING="0"
  6118. CELLSPACING="0"
  6119. CLASS="EXAMPLE"
  6120. ><TR
  6121. ><TD
  6122. ><DIV
  6123. CLASS="example"
  6124. ><A
  6125. NAME="install.unix.gentoo.config.example2"
  6126. ></A
  6127. ><P
  6128. ><B
  6129. >Example 4-9. Install PHP with USE flags</B
  6130. ></P
  6131. ><TABLE
  6132. BORDER="0"
  6133. BGCOLOR="#E0E0E0"
  6134. CELLPADDING="5"
  6135. ><TR
  6136. ><TD
  6137. ><PRE
  6138. CLASS="shell"
  6139. ># USE="-* curl mysql gd" emerge php mod_php</PRE
  6140. ></TD
  6141. ></TR
  6142. ></TABLE
  6143. ></DIV
  6144. ></TD
  6145. ></TR
  6146. ></TABLE
  6147. ><P
  6148. >     As in the last example, do not forget to emerge php as well as mod_php.
  6149.     php is responsible for the command line version of PHP as mod_php is
  6150.     for the Apache module version of PHP.
  6151.    </P
  6152. ></DIV
  6153. ><DIV
  6154. CLASS="sect2"
  6155. ><HR><H3
  6156. CLASS="sect2"
  6157. ><A
  6158. NAME="install.unix.gentoo.faq"
  6159. >Common Problems</A
  6160. ></H3
  6161. ><P
  6162. ></P
  6163. ><UL
  6164. ><LI
  6165. ><P
  6166. >      If you see the PHP source instead of the result the script should
  6167.      produce, you have probably forgot to edit <TT
  6168. CLASS="filename"
  6169. >/etc/conf.d/apache</TT
  6170. >.
  6171.      Apache needs to be started with the -D PHP4 flag. To see if the flag is
  6172.      present, you should be able to see it when using 
  6173.      <B
  6174. CLASS="command"
  6175. >ps ax | grep apache</B
  6176. > while Apache is running.
  6177.     </P
  6178. ></LI
  6179. ><LI
  6180. ><P
  6181. >      Due to slotting problems, you might end up with more than one version
  6182.      of PHP installed on your system. If this is the case, you need to unmerge
  6183.      the old versions manually by using
  6184.      <B
  6185. CLASS="command"
  6186. >emerge unmerge mod_php-<old version></B
  6187. >.
  6188.     </P
  6189. ></LI
  6190. ><LI
  6191. ><P
  6192. >      If you cannot emerge PHP because of Java, try putting <B
  6193. CLASS="command"
  6194. >-*</B
  6195. >
  6196.      in front of your USE flags like in the above examples.
  6197.     </P
  6198. ></LI
  6199. ><LI
  6200. ><P
  6201. >      If you are having problems configuring Apache and PHP, you can always
  6202.      search the <A
  6203. HREF="http://forums.gentoo.org/"
  6204. TARGET="_top"
  6205. >Gentoo Forums</A
  6206. >.
  6207.      Try searching with the keywords "Apache PHP".
  6208.     </P
  6209. ></LI
  6210. ></UL
  6211. ></DIV
  6212. ></DIV
  6213. ></DIV
  6214. ><DIV
  6215. CLASS="chapter"
  6216. ><HR><H1
  6217. ><A
  6218. NAME="install.macosx"
  6219. >Chapter 5. Installation on Mac OS X</A
  6220. ></H1
  6221. ><P
  6222. >   This section contains notes and hints specific to installing
  6223.   PHP on Mac OS X. There are two slightly different versions of
  6224.   Mac OS X, Client and Server, our manual deals with installing
  6225.   PHP on both systems. Note that PHP is not available for MacOS
  6226.   9 and earlier versions. 
  6227.  </P
  6228. ><DIV
  6229. CLASS="sect1"
  6230. ><HR><H2
  6231. CLASS="sect1"
  6232. ><A
  6233. NAME="install.macosx.packages"
  6234. >Using Packages</A
  6235. ></H2
  6236. ><P
  6237. >    There are a few pre-packaged and pre-compiled versions of PHP for
  6238.    Mac OS X. This can help in setting up a standard
  6239.    configuration, but if you need to have a different set of features
  6240.    (such as a secure server, or a different database driver), you may
  6241.    need to build PHP and/or your web server yourself. If you are unfamiliar
  6242.    with building and compiling your own software, it's worth
  6243.    checking whether somebody has already built a packaged
  6244.    version of PHP with the features you need.
  6245.   </P
  6246. ></DIV
  6247. ><DIV
  6248. CLASS="sect1"
  6249. ><HR><H2
  6250. CLASS="sect1"
  6251. ><A
  6252. NAME="install.macosx.server"
  6253. >Compiling for OS X Server</A
  6254. ></H2
  6255. ><DIV
  6256. CLASS="formalpara"
  6257. ><P
  6258. ><A
  6259. NAME="install.macosx.server.compile"
  6260. ></A
  6261. ><B
  6262. >Mac OS X Server install. </B
  6263. >
  6264.     <P
  6265. ></P
  6266. ><OL
  6267. TYPE="1"
  6268. ><LI
  6269. ><P
  6270. >Get the latest distributions of Apache and PHP.</P
  6271. ></LI
  6272. ><LI
  6273. ><P
  6274. >        Untar them, and run the <B
  6275. CLASS="command"
  6276. >configure</B
  6277. > program on Apache
  6278.        like so.
  6279.        <TABLE
  6280. BORDER="0"
  6281. BGCOLOR="#E0E0E0"
  6282. CELLPADDING="5"
  6283. ><TR
  6284. ><TD
  6285. ><PRE
  6286. CLASS="shell"
  6287. >./configure --exec-prefix=/usr \
  6288. --localstatedir=/var \
  6289. --mandir=/usr/share/man \
  6290. --libexecdir=/System/Library/Apache/Modules \
  6291. --iconsdir=/System/Library/Apache/Icons \
  6292. --includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \
  6293. --enable-shared=max \
  6294. --enable-module=most \
  6295. --target=apache</PRE
  6296. ></TD
  6297. ></TR
  6298. ></TABLE
  6299. >
  6300.       </P
  6301. ></LI
  6302. ><LI
  6303. ><P
  6304. >        If you want the compiler to do some optimization, you may also want to
  6305.        add this line:
  6306.        <TABLE
  6307. BORDER="0"
  6308. BGCOLOR="#E0E0E0"
  6309. CELLPADDING="5"
  6310. ><TR
  6311. ><TD
  6312. ><PRE
  6313. CLASS="shell"
  6314. >setenv OPTIM=-O2</PRE
  6315. ></TD
  6316. ></TR
  6317. ></TABLE
  6318. >
  6319.       </P
  6320. ></LI
  6321. ><LI
  6322. ><P
  6323. >        Next, go to the PHP 4 source directory and configure it.
  6324.        <TABLE
  6325. BORDER="0"
  6326. BGCOLOR="#E0E0E0"
  6327. CELLPADDING="5"
  6328. ><TR
  6329. ><TD
  6330. ><PRE
  6331. CLASS="shell"
  6332. >./configure --prefix=/usr \
  6333.     --sysconfdir=/etc \
  6334.     --localstatedir=/var \
  6335.     --mandir=/usr/share/man \
  6336.     --with-xml \
  6337.     --with-apache=/src/apache_1.3.12</PRE
  6338. ></TD
  6339. ></TR
  6340. ></TABLE
  6341. >
  6342.        If you have any other additions (MySQL, GD, etc.), be sure to add them
  6343.        here. For the <VAR
  6344. CLASS="option"
  6345. >--with-apache</VAR
  6346. > string, put
  6347.        in the path to your apache source directory, for example
  6348.        <TT
  6349. CLASS="filename"
  6350. >/src/apache_1.3.12</TT
  6351. >.
  6352.       </P
  6353. ></LI
  6354. ><LI
  6355. ><P
  6356. >        Type <B
  6357. CLASS="command"
  6358. >make</B
  6359. > and <B
  6360. CLASS="command"
  6361. >make install</B
  6362. >. This
  6363.        will add a directory to your Apache source directory under
  6364.        <TT
  6365. CLASS="filename"
  6366. >src/modules/php4</TT
  6367. >.
  6368.       </P
  6369. ></LI
  6370. ><LI
  6371. ><P
  6372. >        Now, reconfigure Apache to build in PHP 4.
  6373.        <TABLE
  6374. BORDER="0"
  6375. BGCOLOR="#E0E0E0"
  6376. CELLPADDING="5"
  6377. ><TR
  6378. ><TD
  6379. ><PRE
  6380. CLASS="shell"
  6381. >./configure --exec-prefix=/usr \
  6382. --localstatedir=/var \
  6383. --mandir=/usr/share/man \
  6384. --libexecdir=/System/Library/Apache/Modules \
  6385. --iconsdir=/System/Library/Apache/Icons \
  6386. --includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \
  6387. --enable-shared=max \
  6388. --enable-module=most \
  6389. --target=apache \
  6390. --activate-module=src/modules/php4/libphp4.a</PRE
  6391. ></TD
  6392. ></TR
  6393. ></TABLE
  6394. >
  6395.        You may get a message telling you that <TT
  6396. CLASS="filename"
  6397. >libmodphp4.a</TT
  6398. > is
  6399.        out of date. If so, go to the <TT
  6400. CLASS="filename"
  6401. >src/modules/php4</TT
  6402. >
  6403.        directory inside your Apache source directory and run this command: 
  6404.        <B
  6405. CLASS="command"
  6406. >ranlib libmodphp4.a</B
  6407. >. Then go back to the root of the
  6408.        Apache source directory and run the above <B
  6409. CLASS="command"
  6410. >configure</B
  6411. >
  6412.        command again. That'll bring the link table up to date. Run
  6413.        <B
  6414. CLASS="command"
  6415. >make</B
  6416. > and <B
  6417. CLASS="command"
  6418. >make install</B
  6419. > again.
  6420.       </P
  6421. ></LI
  6422. ><LI
  6423. ><P
  6424. >        Copy and rename the <TT
  6425. CLASS="filename"
  6426. >php.ini-dist</TT
  6427. > file to your
  6428.        <TT
  6429. CLASS="filename"
  6430. >bin</TT
  6431. > directory from your PHP 4
  6432.        source directory: 
  6433.        <KBD
  6434. CLASS="userinput"
  6435. >cp php.ini-dist /usr/local/bin/php.ini</KBD
  6436. >
  6437.        or (if your don't have a local directory)
  6438.        <KBD
  6439. CLASS="userinput"
  6440. >cp php.ini-dist /usr/bin/php.ini</KBD
  6441. >.
  6442.       </P
  6443. ></LI
  6444. ></OL
  6445. >
  6446.    </P
  6447. ></DIV
  6448. ></DIV
  6449. ><DIV
  6450. CLASS="sect1"
  6451. ><HR><H2
  6452. CLASS="sect1"
  6453. ><A
  6454. NAME="install.macosx.client"
  6455. >Compiling for MacOS X Client</A
  6456. ></H2
  6457. ><P
  6458. >    The following instructions will help you install a PHP module for the Apache
  6459.    web server included in MacOS X. This version includes support for the MySQL
  6460.    and PostgreSQL databases. These instructions are graciously provided by
  6461.    <A
  6462. HREF="http://www.entropy.ch/software/macosx/"
  6463. TARGET="_top"
  6464. >Marc Liyanage</A
  6465. >.
  6466.   </P
  6467. ><DIV
  6468. CLASS="warning"
  6469. ><P
  6470. ></P
  6471. ><TABLE
  6472. CLASS="warning"
  6473. BORDER="1"
  6474. WIDTH="100%"
  6475. ><TR
  6476. ><TD
  6477. ALIGN="CENTER"
  6478. ><B
  6479. >Warning</B
  6480. ></TD
  6481. ></TR
  6482. ><TR
  6483. ><TD
  6484. ALIGN="LEFT"
  6485. ><P
  6486. >     Be careful when you do this, you could screw up your Apache web server!
  6487.    </P
  6488. ></TD
  6489. ></TR
  6490. ></TABLE
  6491. ></DIV
  6492. ><P
  6493. >    Do this to install:
  6494.    <P
  6495. ></P
  6496. ><OL
  6497. TYPE="1"
  6498. ><LI
  6499. ><P
  6500. >       Open a terminal window.
  6501.      </P
  6502. ></LI
  6503. ><LI
  6504. ><P
  6505. >       Type
  6506.       <KBD
  6507. CLASS="userinput"
  6508. >wget http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz</KBD
  6509. >,
  6510.       wait for the download to finish.
  6511.      </P
  6512. ></LI
  6513. ><LI
  6514. ><P
  6515. >       Type <KBD
  6516. CLASS="userinput"
  6517. >gunzip libphp4.so.gz</KBD
  6518. >.
  6519.      </P
  6520. ></LI
  6521. ><LI
  6522. ><P
  6523. >       Type <KBD
  6524. CLASS="userinput"
  6525. >sudo apxs -i -a -n php4 libphp4.so</KBD
  6526. >
  6527.      </P
  6528. ></LI
  6529. ><LI
  6530. ><P
  6531. >       Now type <KBD
  6532. CLASS="userinput"
  6533. >sudo open -a TextEdit /etc/httpd/httpd.conf</KBD
  6534. >.
  6535.       TextEdit will open with the web server configuration file. Locate these 
  6536.       two lines towards the end of the file: (Use the Find command)
  6537.       <TABLE
  6538. BORDER="0"
  6539. BGCOLOR="#E0E0E0"
  6540. CELLPADDING="5"
  6541. ><TR
  6542. ><TD
  6543. ><PRE
  6544. CLASS="apache"
  6545. >#AddType application/x-httpd-php .php 
  6546. #AddType application/x-httpd-php-source .phps</PRE
  6547. ></TD
  6548. ></TR
  6549. ></TABLE
  6550. >
  6551.        Remove the two hash marks (<VAR
  6552. CLASS="literal"
  6553. >#</VAR
  6554. >), then save the file and
  6555.        quit TextEdit.
  6556.       </P
  6557. ></LI
  6558. ><LI
  6559. ><P
  6560. >       Finally, type <KBD
  6561. CLASS="userinput"
  6562. >sudo apachectl graceful</KBD
  6563. > to restart
  6564.       the web server.
  6565.      </P
  6566. ></LI
  6567. ></OL
  6568. >
  6569.   </P
  6570. ><P
  6571. >    PHP should now be up and running. You can test it by dropping a file into 
  6572.    your <TT
  6573. CLASS="filename"
  6574. >Sites</TT
  6575. > folder which is called
  6576.    <TT
  6577. CLASS="filename"
  6578. >test.php</TT
  6579. >. Into that file, write this line:
  6580.    <VAR
  6581. CLASS="literal"
  6582. ><?php phpinfo() ?></VAR
  6583. >.
  6584.   </P
  6585. ><P
  6586. >    Now open up <VAR
  6587. CLASS="literal"
  6588. >127.0.0.1/~your_username/test.php</VAR
  6589. > in your web
  6590.    browser. You should see a status table with information about the PHP module.
  6591.   </P
  6592. ></DIV
  6593. ></DIV
  6594. ><DIV
  6595. CLASS="chapter"
  6596. ><HR><H1
  6597. ><A
  6598. NAME="install.windows"
  6599. >Chapter 6. Installation on Windows systems</A
  6600. ></H1
  6601. ><P
  6602. >     This section applies to Windows 98/Me and Windows NT/2000/XP/2003. PHP 
  6603.     will not work on 16 bit platforms such as Windows 3.1 and sometimes 
  6604.     we refer to the supported Windows platforms as Win32. Windows 95
  6605.     is no longer supported as of PHP 4.3.0.
  6606.    </P
  6607. ><P
  6608. >     There are two main ways to install PHP for Windows: either
  6609.     <A
  6610. HREF="#install.windows.manual"
  6611. >manually</A
  6612. >
  6613.     or by using the <A
  6614. HREF="#install.windows.installer"
  6615. >installer</A
  6616. >.
  6617.    </P
  6618. ><P
  6619. >     If you have Microsoft Visual Studio, you can also 
  6620.     <A
  6621. HREF="#install.windows.building"
  6622. >build</A
  6623. >
  6624.     PHP from the original source code.
  6625.    </P
  6626. ><P
  6627. >     Once you have PHP installed on your Windows system, you may also
  6628.     want to <A
  6629. HREF="#install.windows.extensions"
  6630. >load various extensions</A
  6631. >
  6632.     for added functionality.
  6633.    </P
  6634. ><DIV
  6635. CLASS="warning"
  6636. ><P
  6637. ></P
  6638. ><TABLE
  6639. CLASS="warning"
  6640. BORDER="1"
  6641. WIDTH="100%"
  6642. ><TR
  6643. ><TD
  6644. ALIGN="CENTER"
  6645. ><B
  6646. >Warning</B
  6647. ></TD
  6648. ></TR
  6649. ><TR
  6650. ><TD
  6651. ALIGN="LEFT"
  6652. ><P
  6653. >      There are several all-in-one installers over the Internet, but none of
  6654.      those are endorsed by PHP.net, as we believe that the manual installation
  6655.      is the best choice to have your system secure and optimised.
  6656.     </P
  6657. ></TD
  6658. ></TR
  6659. ></TABLE
  6660. ></DIV
  6661. ><DIV
  6662. CLASS="sect1"
  6663. ><HR><H2
  6664. CLASS="sect1"
  6665. ><A
  6666. NAME="install.windows.installer"
  6667. >Windows Installer</A
  6668. ></H2
  6669. ><P
  6670. >      The Windows PHP installer is available from the downloads page at
  6671.      <A
  6672. HREF="http://www.php.net/downloads.php"
  6673. TARGET="_top"
  6674. >http://www.php.net/downloads.php</A
  6675. >. This
  6676.      installs the <SPAN
  6677. CLASS="emphasis"
  6678. ><I
  6679. CLASS="emphasis"
  6680. >CGI version</I
  6681. ></SPAN
  6682. > of PHP and for IIS, PWS,
  6683.      and Xitami, it configures the web server as well.  The installer does not 
  6684.      include any extra external PHP extensions (php_*.dll) as you'll only find 
  6685.      those in the Windows Zip Package and <ACRONYM
  6686. CLASS="acronym"
  6687. >PECL</ACRONYM
  6688. > downloads.
  6689.     </P
  6690. ><DIV
  6691. CLASS="note"
  6692. ><BLOCKQUOTE
  6693. CLASS="note"
  6694. ><P
  6695. ><B
  6696. >Note: </B
  6697. >
  6698.       While the Windows installer is an easy way to make PHP work, it is 
  6699.       restricted in many aspects as, for example, the automatic setup of 
  6700.       extensions is not supported.  Use of the installer isn't the preferred 
  6701.       method for installing PHP.
  6702.      </P
  6703. ></BLOCKQUOTE
  6704. ></DIV
  6705. ><P
  6706. >      First, install your selected <ACRONYM
  6707. CLASS="acronym"
  6708. >HTTP</ACRONYM
  6709. > (web) server on your 
  6710.      system, and make sure that it works.
  6711.     </P
  6712. ><P
  6713. >      Run the executable installer and follow the instructions provided by the
  6714.      installation wizard. Two types of installation are supported - standard,
  6715.      which provides sensible defaults for all the settings it can, and advanced,
  6716.      which asks questions as it goes along.
  6717.     </P
  6718. ><P
  6719. >      The installation wizard gathers enough information to set up the <TT
  6720. CLASS="filename"
  6721. >php.ini</TT
  6722. >
  6723.      file, and configure certain web servers to use PHP. One of the web servers
  6724.      the PHP installer does not configure for is Apache, so you'll need to
  6725.      configure it manually.
  6726.     </P
  6727. ><P
  6728. >      Once the installation has completed, the installer will inform you if you
  6729.      need to restart your system, restart the server, or just start using PHP.
  6730.     </P
  6731. ><DIV
  6732. CLASS="warning"
  6733. ><P
  6734. ></P
  6735. ><TABLE
  6736. CLASS="warning"
  6737. BORDER="1"
  6738. WIDTH="100%"
  6739. ><TR
  6740. ><TD
  6741. ALIGN="CENTER"
  6742. ><B
  6743. >Warning</B
  6744. ></TD
  6745. ></TR
  6746. ><TR
  6747. ><TD
  6748. ALIGN="LEFT"
  6749. ><P
  6750. >       Be aware, that this setup of PHP is not secure. If you would like to have
  6751.       a secure PHP setup, you'd better go on the manual way, and set every
  6752.       option carefully. This automatically working setup gives you an instantly
  6753.       working PHP installation, but it is not meant to be used on online servers.
  6754.      </P
  6755. ></TD
  6756. ></TR
  6757. ></TABLE
  6758. ></DIV
  6759. ></DIV
  6760. ><DIV
  6761. CLASS="sect1"
  6762. ><HR><H2
  6763. CLASS="sect1"
  6764. ><A
  6765. NAME="install.windows.manual"
  6766. >Manual Installation Steps</A
  6767. ></H2
  6768. ><P
  6769. >      This install guide will help you manually install and configure PHP with
  6770.      a web server on Microsoft Windows.  To get started you'll need to download 
  6771.      the zip binary distribution from the downloads page at
  6772.      <A
  6773. HREF="http://www.php.net/downloads.php"
  6774. TARGET="_top"
  6775. >http://www.php.net/downloads.php</A
  6776. >.
  6777.     </P
  6778. ><P
  6779. >      Although there are many all-in-one installation kits, and we also 
  6780.      distribute a PHP installer for Microsoft Windows, we recommend you take 
  6781.      the time to setup PHP yourself as this will provide you with a better 
  6782.      understanding of the system, and enables you to install PHP extensions 
  6783.      easily when needed.
  6784.     </P
  6785. ><DIV
  6786. CLASS="note"
  6787. ><BLOCKQUOTE
  6788. CLASS="note"
  6789. ><A
  6790. NAME="install.windows.manual.upgrade"
  6791. ></A
  6792. ><P
  6793. ><B
  6794. >Upgrading from a previous PHP version: </B
  6795. >
  6796.       Previous editions of the manual suggest moving various ini and 
  6797.       <ACRONYM
  6798. CLASS="acronym"
  6799. >DLL</ACRONYM
  6800. > files into your SYSTEM (i.e. 
  6801.       <TT
  6802. CLASS="filename"
  6803. >C:\WINDOWS</TT
  6804. >) folder and while this 
  6805.       simplifies the installation procedure it makes upgrading difficult.  We 
  6806.       advise you remove all of these files (like <TT
  6807. CLASS="filename"
  6808. >php.ini</TT
  6809. > and PHP related
  6810.       DLLs from the Windows SYSTEM folder) before moving on with a new 
  6811.       PHP installation.  Be sure to backup these files as you might break the
  6812.       entire system.  The old <TT
  6813. CLASS="filename"
  6814. >php.ini</TT
  6815. > might be useful in setting up the new
  6816.       PHP as well.  And as you'll soon learn, the preferred method for 
  6817.       installing PHP is to keep all PHP related files in one directory and
  6818.       have this directory available to your systems PATH.
  6819.      </P
  6820. ></BLOCKQUOTE
  6821. ></DIV
  6822. ><DIV
  6823. CLASS="note"
  6824. ><BLOCKQUOTE
  6825. CLASS="note"
  6826. ><P
  6827. ><B
  6828. >MDAC requirements: </B
  6829. >
  6830.       If you use Microsoft <SPAN
  6831. CLASS="emphasis"
  6832. ><I
  6833. CLASS="emphasis"
  6834. >Windows 98/NT4</I
  6835. ></SPAN
  6836. > download the
  6837.       latest version of the Microsoft Data Access Components (MDAC) for your
  6838.       platform. MDAC is available at <A
  6839. HREF="http://msdn.microsoft.com/data/"
  6840. TARGET="_top"
  6841. >http://msdn.microsoft.com/data/</A
  6842. >.
  6843.       This requirement exists because <A
  6844. HREF="#ref.uodbc"
  6845. >ODBC</A
  6846. > is
  6847.       built into the distributed Windows binaries.
  6848.      </P
  6849. ></BLOCKQUOTE
  6850. ></DIV
  6851. ><P
  6852. >      The following steps should be completed on all installations before any
  6853.      server specific instructions are performed:
  6854.     </P
  6855. ><P
  6856. >      Extract the distribution file into a directory of your choice. If you
  6857.      are installing PHP 4, extract to <TT
  6858. CLASS="filename"
  6859. >C:\</TT
  6860. >, as the zip file expands to a
  6861.      foldername like <TT
  6862. CLASS="filename"
  6863. >php-4.3.7-Win32</TT
  6864. >. If you are
  6865.      installing PHP 5, extract to <TT
  6866. CLASS="filename"
  6867. >C:\php</TT
  6868. > as the zip file doesn't expand as in
  6869.      PHP 4. You may choose a different location but do not have spaces in the
  6870.      path (like <TT
  6871. CLASS="filename"
  6872. >C:\Program Files\PHP</TT
  6873. >)
  6874.      as some web servers will crash if you do.
  6875.     </P
  6876. ><P
  6877. >      The directory structure extracted from the zip is different for PHP 
  6878.      versions 4 and 5 and look like as follows:
  6879.     </P
  6880. ><TABLE
  6881. WIDTH="100%"
  6882. BORDER="0"
  6883. CELLPADDING="0"
  6884. CELLSPACING="0"
  6885. CLASS="EXAMPLE"
  6886. ><TR
  6887. ><TD
  6888. ><DIV
  6889. CLASS="example"
  6890. ><A
  6891. NAME="AEN1041"
  6892. ></A
  6893. ><P
  6894. ><B
  6895. >Example 6-1. PHP 4 package structure</B
  6896. ></P
  6897. ><TABLE
  6898. BORDER="0"
  6899. BGCOLOR="#E0E0E0"
  6900. CELLPADDING="5"
  6901. ><TR
  6902. ><TD
  6903. ><PRE
  6904. CLASS="programlisting"
  6905. >c:\php
  6906.    |
  6907.    +--cli
  6908.    |  |
  6909.    |  |-php.exe           -- CLI executable - ONLY for commandline scripting
  6910.    |
  6911.    +--dlls                -- support DLLs required by some extensions
  6912.    |  |
  6913.    |  |-expat.dll
  6914.    |  |
  6915.    |  |-fdftk.dll
  6916.    |  |
  6917.    |  |-...
  6918.    |
  6919.    +--extensions          -- extension DLLs for PHP
  6920.    |  |
  6921.    |  |-php_bz2.dll
  6922.    |  |
  6923.    |  |-php_cpdf.dll
  6924.    |  |
  6925.    |  |-..
  6926.    |
  6927.    +--mibs                -- support files for SNMP
  6928.    |
  6929.    +--openssl             -- support files for Openssl
  6930.    |
  6931.    +--pdf-related         -- support files for PDF
  6932.    |
  6933.    +--sapi                -- SAPI (server module support) DLLs
  6934.    |  |
  6935.    |  |-php4activescript.dll
  6936.    |  |
  6937.    |  |-php4apache.dll
  6938.    |  |
  6939.    |  |-php4apache2.dll
  6940.    |  |
  6941.    |  |-..
  6942.    |
  6943.    +--PEAR                -- initial copy of PEAR
  6944.    |
  6945.    |
  6946.    |-go-pear.bat          -- PEAR setup script
  6947.    |
  6948.    |-..
  6949.    |
  6950.    |-php.exe              -- CGI executable
  6951.    |
  6952.    |-..
  6953.    |
  6954.    |-php.ini-dist         -- default php.ini settings
  6955.    |
  6956.    |-php.ini-recommended  -- recommended php.ini settings
  6957.    | 
  6958.    |-php4ts.dll           -- core PHP DLL
  6959.    | 
  6960.    |-...</PRE
  6961. ></TD
  6962. ></TR
  6963. ></TABLE
  6964. ></DIV
  6965. ></TD
  6966. ></TR
  6967. ></TABLE
  6968. ><P
  6969. >     Or:
  6970.     </P
  6971. ><TABLE
  6972. WIDTH="100%"
  6973. BORDER="0"
  6974. CELLPADDING="0"
  6975. CELLSPACING="0"
  6976. CLASS="EXAMPLE"
  6977. ><TR
  6978. ><TD
  6979. ><DIV
  6980. CLASS="example"
  6981. ><A
  6982. NAME="AEN1045"
  6983. ></A
  6984. ><P
  6985. ><B
  6986. >Example 6-2. PHP 5 package structure</B
  6987. ></P
  6988. ><TABLE
  6989. BORDER="0"
  6990. BGCOLOR="#E0E0E0"
  6991. CELLPADDING="5"
  6992. ><TR
  6993. ><TD
  6994. ><PRE
  6995. CLASS="programlisting"
  6996. >c:\php
  6997.    |
  6998.    +--dev
  6999.    |  |
  7000.    |  |-php5ts.lib
  7001.    |
  7002.    +--ext                 -- extension DLLs for PHP
  7003.    |  |
  7004.    |  |-php_bz2.dll
  7005.    |  |
  7006.    |  |-php_cpdf.dll
  7007.    |  |
  7008.    |  |-..
  7009.    |
  7010.    +--extras
  7011.    |  |
  7012.    |  +--mibs             -- support files for SNMP
  7013.    |  |
  7014.    |  +--openssl          -- support files for Openssl
  7015.    |  |
  7016.    |  +--pdf-related      -- support files for PDF
  7017.    |  |
  7018.    |  |-mime.magic
  7019.    |
  7020.    +--pear                -- initial copy of PEAR
  7021.    |
  7022.    |
  7023.    |-go-pear.bat          -- PEAR setup script
  7024.    |
  7025.    |-fdftk.dll
  7026.    |
  7027.    |-..
  7028.    |
  7029.    |-php-cgi.exe          -- CGI executable
  7030.    |
  7031.    |-php-win.exe          -- executes scripts without an opened command prompt
  7032.    |
  7033.    |-php.exe              -- CLI executable - ONLY for command line scripting
  7034.    |
  7035.    |-..
  7036.    |
  7037.    |-php.ini-dist         -- default php.ini settings
  7038.    |
  7039.    |-php.ini-recommended  -- recommended php.ini settings
  7040.    | 
  7041.    |-php5activescript.dll
  7042.    |
  7043.    |-php5apache.dll
  7044.    |
  7045.    |-php5apache2.dll
  7046.    |
  7047.    |-..
  7048.    |
  7049.    |-php5ts.dll           -- core PHP DLL
  7050.    | 
  7051.    |-...</PRE
  7052. ></TD
  7053. ></TR
  7054. ></TABLE
  7055. ></DIV
  7056. ></TD
  7057. ></TR
  7058. ></TABLE
  7059. ><P
  7060. >      Notice the differences and similarities.  Both PHP 4 and PHP 5 have a 
  7061.      <ACRONYM
  7062. CLASS="acronym"
  7063. >CGI</ACRONYM
  7064. > executable, a <ACRONYM
  7065. CLASS="acronym"
  7066. >CLI</ACRONYM
  7067. > executable,
  7068.      and server modules, but they are located in different folders and/or have
  7069.      different names.  While PHP 4 packages have the server modules in the 
  7070.      <TT
  7071. CLASS="filename"
  7072. >sapi</TT
  7073. > folder, PHP 5 
  7074.      distributions have no such directory and instead they're in the PHP
  7075.      folder root. The supporting DLLs for the PHP 5 extensions are also not
  7076.      in a seperate directory.
  7077.     </P
  7078. ><DIV
  7079. CLASS="note"
  7080. ><BLOCKQUOTE
  7081. CLASS="note"
  7082. ><P
  7083. ><B
  7084. >Note: </B
  7085. >
  7086.       In PHP 4, you should move all files located in the <TT
  7087. CLASS="filename"
  7088. >dll</TT
  7089. > and <TT
  7090. CLASS="filename"
  7091. >sapi</TT
  7092. > folders to the main folder (e.g.
  7093.       <TT
  7094. CLASS="filename"
  7095. >C:\php</TT
  7096. >).
  7097.      </P
  7098. ></BLOCKQUOTE
  7099. ></DIV
  7100. ><P
  7101. >      Here is a list of server modules shipped with PHP 4 and PHP 5:
  7102.      <P
  7103. ></P
  7104. ><UL
  7105. ><LI
  7106. ><P
  7107. >        <TT
  7108. CLASS="filename"
  7109. >sapi/php4activescript.dll (php5activescript.dll)</TT
  7110. >
  7111.        - <A
  7112. HREF="#install.windows.activescript"
  7113. >ActiveScript
  7114.         engine</A
  7115. >, allowing you to embed PHP in your Windows
  7116.        applications.
  7117.       </P
  7118. ></LI
  7119. ><LI
  7120. ><P
  7121. >        <TT
  7122. CLASS="filename"
  7123. >sapi/php4apache.dll (php5apache.dll)</TT
  7124. > - Apache 1.3.x module.
  7125.       </P
  7126. ></LI
  7127. ><LI
  7128. ><P
  7129. >        <TT
  7130. CLASS="filename"
  7131. >sapi/php4apache2.dll (php5apache2.dll)</TT
  7132. > - Apache 2.0.x module.
  7133.       </P
  7134. ></LI
  7135. ><LI
  7136. ><P
  7137. >        <TT
  7138. CLASS="filename"
  7139. >sapi/php4isapi.dll (php5isapi.dll)</TT
  7140. > - ISAPI Module
  7141.        for ISAPI compliant web servers like IIS 4.0/PWS 4.0 or newer.
  7142.       </P
  7143. ></LI
  7144. ><LI
  7145. ><P
  7146. >        <TT
  7147. CLASS="filename"
  7148. >sapi/php4nsapi.dll (php5nsapi.dll)</TT
  7149. > - Sun/iPlanet/Netscape
  7150.        server module.
  7151.       </P
  7152. ></LI
  7153. ><LI
  7154. ><P
  7155. >        <TT
  7156. CLASS="filename"
  7157. >sapi/php4pi3web.dll (no equivalent in PHP 5)</TT
  7158. > - Pi3Web server module.
  7159.       </P
  7160. ></LI
  7161. ></UL
  7162. >
  7163.     </P
  7164. ><P
  7165. >      Server modules provide significantly better performance and additional 
  7166.      functionality compared to the CGI binary. The CLI version is designed to
  7167.      let you use PHP for command line scripting. More information about CLI is
  7168.      available in the chapter about <A
  7169. HREF="#features.commandline"
  7170. >using
  7171.      PHP from the command line</A
  7172. >.
  7173.     </P
  7174. ><DIV
  7175. CLASS="warning"
  7176. ><P
  7177. ></P
  7178. ><TABLE
  7179. CLASS="warning"
  7180. BORDER="1"
  7181. WIDTH="100%"
  7182. ><TR
  7183. ><TD
  7184. ALIGN="CENTER"
  7185. ><B
  7186. >Warning</B
  7187. ></TD
  7188. ></TR
  7189. ><TR
  7190. ><TD
  7191. ALIGN="LEFT"
  7192. ><P
  7193. >       The SAPI modules have been significantly improved as of the 4.1 release,
  7194.       however, in older systems you may encounter server errors or other
  7195.       server modules failing, such as ASP.
  7196.      </P
  7197. ></TD
  7198. ></TR
  7199. ></TABLE
  7200. ></DIV
  7201. ><P
  7202. >      The CGI and CLI binaries, and the web server modules all require the
  7203.      <TT
  7204. CLASS="filename"
  7205. >php4ts.dll</TT
  7206. > (<TT
  7207. CLASS="filename"
  7208. >php5ts.dll</TT
  7209. >) file to
  7210.      be available to them. You have to make sure that this file can be found
  7211.      by your PHP installation. The search order for this DLL is as follows:
  7212.      <P
  7213. ></P
  7214. ><UL
  7215. ><LI
  7216. ><P
  7217. >         The same directory from where <TT
  7218. CLASS="filename"
  7219. >php.exe</TT
  7220. > is called,
  7221.         or in case you use a SAPI module, the web server's directory (e.g.
  7222.         <TT
  7223. CLASS="filename"
  7224. >C:\Program Files\Apache Group\Apache2\bin</TT
  7225. >).
  7226.        </P
  7227. ></LI
  7228. ><LI
  7229. ><P
  7230. >         Any directory in your Windows <VAR
  7231. CLASS="varname"
  7232. >PATH</VAR
  7233. > environment
  7234.         variable.
  7235.        </P
  7236. ></LI
  7237. ></UL
  7238. >
  7239.     </P
  7240. ><P
  7241. >      To make <TT
  7242. CLASS="filename"
  7243. >php4ts.dll</TT
  7244. > / <TT
  7245. CLASS="filename"
  7246. >php5ts.dll</TT
  7247. >
  7248.      available you have three options: copy the file to the Windows system
  7249.      directory, copy the file to the web server's directory, or add your PHP
  7250.      directory, <TT
  7251. CLASS="filename"
  7252. >C:\php</TT
  7253. > to the
  7254.      <VAR
  7255. CLASS="varname"
  7256. >PATH</VAR
  7257. >. For better maintenance, we advise you to follow
  7258.      the last option, add <TT
  7259. CLASS="filename"
  7260. >C:\php</TT
  7261. > to the
  7262.      <VAR
  7263. CLASS="varname"
  7264. >PATH</VAR
  7265. >, because it will be simpler to upgrade PHP in the
  7266.      future. Read more about how to add your PHP directory to
  7267.      <VAR
  7268. CLASS="varname"
  7269. >PATH</VAR
  7270. > in the <A
  7271. HREF="#faq.installation.addtopath"
  7272. >corresponding FAQ entry</A
  7273. >.
  7274.     </P
  7275. ><P
  7276. >      The next step is to set up a valid configuration file for PHP, <TT
  7277. CLASS="filename"
  7278. >php.ini</TT
  7279. >.
  7280.      There are two ini files distributed in the zip file,
  7281.      <TT
  7282. CLASS="filename"
  7283. >php.ini-dist</TT
  7284. > and
  7285.      <TT
  7286. CLASS="filename"
  7287. >php.ini-recommended</TT
  7288. >. We advise you to use
  7289.      <TT
  7290. CLASS="filename"
  7291. >php.ini-recommended</TT
  7292. >, because we optimized the
  7293.      default settings in this file for performance, and security. Read this
  7294.      well documented file carefully because it has changes from
  7295.      <TT
  7296. CLASS="filename"
  7297. >php.ini-dist</TT
  7298. > that will drastically affect your 
  7299.      setup.  Some examples are <A
  7300. HREF="#ini.display-errors"
  7301. >      display_errors</A
  7302. > being <VAR
  7303. CLASS="literal"
  7304. >off</VAR
  7305. > and 
  7306.      <A
  7307. HREF="#ini.magic-quotes-gpc"
  7308. >magic_quotes_gpc</A
  7309. > being
  7310.      <VAR
  7311. CLASS="literal"
  7312. >off</VAR
  7313. >.  In addition to reading these, study the <A
  7314. HREF="#configuration.file"
  7315. >ini settings</A
  7316. > and set every element
  7317.      manually yourself. If you would like to achieve the best security, then
  7318.      this is the way for you, although PHP works fine with these default ini
  7319.      files. Copy your chosen ini-file to a directory that PHP is able to find
  7320.      and rename it to <TT
  7321. CLASS="filename"
  7322. >php.ini</TT
  7323. >. PHP searches for <TT
  7324. CLASS="filename"
  7325. >php.ini</TT
  7326. > in the following
  7327.      locations (in order):
  7328.      <P
  7329. ></P
  7330. ><UL
  7331. ><LI
  7332. ><P
  7333. >         PHPIniDir directive (Apache 2 module only)
  7334.        </P
  7335. ></LI
  7336. ><LI
  7337. ><P
  7338. >         <VAR
  7339. CLASS="literal"
  7340. >HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath</VAR
  7341. >
  7342.        </P
  7343. ></LI
  7344. ><LI
  7345. ><P
  7346. >         The <VAR
  7347. CLASS="varname"
  7348. >PHPRC</VAR
  7349. > environment variable
  7350.        </P
  7351. ></LI
  7352. ><LI
  7353. ><P
  7354. >         Directory of PHP (for CLI), or the web server's directory (for 
  7355.         SAPI modules)
  7356.        </P
  7357. ></LI
  7358. ><LI
  7359. ><P
  7360. >         Windows directory (<TT
  7361. CLASS="filename"
  7362. >C:\windows</TT
  7363. >
  7364.         or <TT
  7365. CLASS="filename"
  7366. >C:\winnt</TT
  7367. >)
  7368.        </P
  7369. ></LI
  7370. ></UL
  7371. > 
  7372.     </P
  7373. ><P
  7374. >      If you are running Apache 2, the simpler option is to use the PHPIniDir
  7375.      directive (read the <A
  7376. HREF="#install.windows.apache2"
  7377. >installation
  7378.      on Apache 2</A
  7379. > page), otherwise your best option is to set the
  7380.      <VAR
  7381. CLASS="varname"
  7382. >PHPRC</VAR
  7383. > environment variable. This process is explained
  7384.      in the following <A
  7385. HREF="#faq.installation.phprc"
  7386. >FAQ entry</A
  7387. >.
  7388.     </P
  7389. ><DIV
  7390. CLASS="note"
  7391. ><BLOCKQUOTE
  7392. CLASS="note"
  7393. ><P
  7394. ><B
  7395. >Note: </B
  7396. >
  7397.       If you're using NTFS on Windows NT, 2000, XP or 2003, make sure that the
  7398.       user running the web server has read permissions to your <TT
  7399. CLASS="filename"
  7400. >php.ini</TT
  7401. > (e.g.
  7402.       make it readable by Everyone).
  7403.      </P
  7404. ></BLOCKQUOTE
  7405. ></DIV
  7406. ><P
  7407. >      The following steps are optional:
  7408.      <P
  7409. ></P
  7410. ><UL
  7411. ><LI
  7412. ><P
  7413. >         Edit your new <TT
  7414. CLASS="filename"
  7415. >php.ini</TT
  7416. > file.       
  7417.         If you plan to use <A
  7418. HREF="#install.windows.omnihttpd"
  7419. >OmniHTTPd</A
  7420. >,
  7421.         do not follow the next step. Set the
  7422.         <A
  7423. HREF="#ini.doc-root"
  7424. >doc_root</A
  7425. > to point to your 
  7426.         web servers document_root. For example:
  7427.         <DIV
  7428. CLASS="informalexample"
  7429. ><P
  7430. ></P
  7431. ><A
  7432. NAME="AEN1144"
  7433. ></A
  7434. ><TABLE
  7435. BORDER="0"
  7436. BGCOLOR="#E0E0E0"
  7437. CELLPADDING="5"
  7438. ><TR
  7439. ><TD
  7440. ><PRE
  7441. CLASS="ini"
  7442. >doc_root = c:\inetpub\wwwroot // for IIS/PWS
  7443.  
  7444. doc_root = c:\apache\htdocs // for Apache</PRE
  7445. ></TD
  7446. ></TR
  7447. ></TABLE
  7448. ><P
  7449. ></P
  7450. ></DIV
  7451. >
  7452.        </P
  7453. ></LI
  7454. ><LI
  7455. ><P
  7456. >         Choose the extensions you would like to load when PHP starts. See
  7457.         the section about
  7458.         <A
  7459. HREF="#install.windows.extensions"
  7460. >Windows extensions</A
  7461. >,
  7462.         about how to set up one, and what is already built in. Note that on
  7463.         a new installation it is advisable to first get PHP working and tested
  7464.         without any extensions before enabling them in <TT
  7465. CLASS="filename"
  7466. >php.ini</TT
  7467. >.
  7468.        </P
  7469. ></LI
  7470. ><LI
  7471. ><P
  7472. >         On PWS and IIS, you can set the
  7473.         <A
  7474. HREF="#ini.browscap"
  7475. >browscap</A
  7476. > configuration setting
  7477.         to point to:
  7478.         <TT
  7479. CLASS="filename"
  7480. >c:\windows\system\inetsrv\browscap.ini</TT
  7481. > on
  7482.         Windows 9x/Me,
  7483.         <TT
  7484. CLASS="filename"
  7485. >c:\winnt\system32\inetsrv\browscap.ini</TT
  7486. > on
  7487.         NT/2000, and
  7488.         <TT
  7489. CLASS="filename"
  7490. >c:\windows\system32\inetsrv\browscap.ini</TT
  7491. >
  7492.         on XP.  For an up-to-date <TT
  7493. CLASS="filename"
  7494. >browscap.ini</TT
  7495. >, read the
  7496.         following <A
  7497. HREF="#faq.obtaining.browscap"
  7498. >FAQ</A
  7499. >.
  7500.        </P
  7501. ></LI
  7502. ></UL
  7503. >
  7504.     </P
  7505. ><P
  7506. >      PHP is now setup on your system.  The next step is to choose a web
  7507.      server, and enable it to run PHP.  Choose a webserver from the table of 
  7508.      contents.
  7509.     </P
  7510. ></DIV
  7511. ><DIV
  7512. CLASS="sect1"
  7513. ><HR><H2
  7514. CLASS="sect1"
  7515. ><A
  7516. NAME="install.windows.activescript"
  7517. >ActiveScript</A
  7518. ></H2
  7519. ><P
  7520. >      This section contains notes specific to the ActiveScript installation.
  7521.     </P
  7522. ><P
  7523. >      ActiveScript is a windows only SAPI that enables you to use PHP script in
  7524.      any ActiveScript compliant host, like Windows Script Host, ASP/ASP.NET,
  7525.      Windows Script Components or Microsoft Scriptlet control.
  7526.     </P
  7527. ><P
  7528. >      As of PHP 5.0.1, ActiveScript has been moved to the <A
  7529. HREF="http://pecl.php.net"
  7530. TARGET="_top"
  7531. >PECL</A
  7532. > repository. You may download this <ACRONYM
  7533. CLASS="acronym"
  7534. >PECL</ACRONYM
  7535. >
  7536. extension <ACRONYM
  7537. CLASS="acronym"
  7538. >DLL</ACRONYM
  7539. > from the <A
  7540. HREF="http://www.php.net/downloads.php"
  7541. TARGET="_top"
  7542. > PHP Downloads</A
  7543. > page or at <A
  7544. HREF="http://snaps.php.net/"
  7545. TARGET="_top"
  7546. > http://snaps.php.net/</A
  7547. >.
  7548.     </P
  7549. ><DIV
  7550. CLASS="note"
  7551. ><BLOCKQUOTE
  7552. CLASS="note"
  7553. ><P
  7554. ><B
  7555. >Note: </B
  7556. >
  7557.       You should read the <A
  7558. HREF="#install.windows.manual"
  7559. >manual
  7560.        installation steps</A
  7561. > first!
  7562.      </P
  7563. ></BLOCKQUOTE
  7564. ></DIV
  7565. ><P
  7566. >      After installing PHP, you should download the ActiveScript DLL
  7567.      (<TT
  7568. CLASS="filename"
  7569. >php5activescript.dll</TT
  7570. >) and place it in the main PHP
  7571.      folder (e.g. <TT
  7572. CLASS="filename"
  7573. >C:\php</TT
  7574. >).
  7575.     </P
  7576. ><P
  7577. >      After having all the files needed, you must register the DLL on your
  7578.      system. To achieve this, open a Command Prompt window (located in the
  7579.      Start Menu). Then go to your PHP directory by typing something like
  7580.      <VAR
  7581. CLASS="literal"
  7582. >cd C:\php</VAR
  7583. >. To register the DLL just type
  7584.      <VAR
  7585. CLASS="literal"
  7586. >regsvr32 php5activescript.dll</VAR
  7587. >.
  7588.     </P
  7589. ><P
  7590. >      To test if ActiveScript is working, create a new file, named
  7591.      <VAR
  7592. CLASS="literal"
  7593. >test.wsf</VAR
  7594. > (the extension is very important) and type:
  7595.      <TABLE
  7596. BORDER="0"
  7597. BGCOLOR="#E0E0E0"
  7598. CELLPADDING="5"
  7599. ><TR
  7600. ><TD
  7601. ><PRE
  7602. CLASS="programlisting"
  7603. ><job id="test">
  7604.  
  7605.  <script language="PHPScript">
  7606.   $WScript->Echo("Hello World!");
  7607.  </script>
  7608.  
  7609. </job></PRE
  7610. ></TD
  7611. ></TR
  7612. ></TABLE
  7613. >
  7614.      Save and double-click on the file. If you receive a little window saying
  7615.      "Hello World!" you're done.
  7616.     </P
  7617. ><DIV
  7618. CLASS="note"
  7619. ><BLOCKQUOTE
  7620. CLASS="note"
  7621. ><P
  7622. ><B
  7623. >Note: </B
  7624. >
  7625.       ActiveScript doesn't use the default <TT
  7626. CLASS="filename"
  7627. >php.ini</TT
  7628. > file. Instead, it will
  7629.       look only in the same directory as the .exe that caused it to load. You
  7630.       should create <TT
  7631. CLASS="filename"
  7632. >php-activescript.ini</TT
  7633. > and place it in
  7634.       that folder, if you wish to load extensions, etc.
  7635.      </P
  7636. ></BLOCKQUOTE
  7637. ></DIV
  7638. ></DIV
  7639. ><DIV
  7640. CLASS="sect1"
  7641. ><HR><H2
  7642. CLASS="sect1"
  7643. ><A
  7644. NAME="install.windows.iis"
  7645. >Microsoft IIS / PWS</A
  7646. ></H2
  7647. ><P
  7648. >     This section contains notes and hints specific to IIS (Microsoft
  7649.     Internet Information Server). We have included installation
  7650.     instructions for <A
  7651. HREF="#install.windows.iis.iis3"
  7652. >PWS/IIS 3</A
  7653. >,
  7654.     <A
  7655. HREF="#install.windows.iis.pws4"
  7656. >PWS 4 or newer</A
  7657. > and
  7658.     <A
  7659. HREF="#install.windows.iis.iis4"
  7660. >IIS 4 or newer</A
  7661. > versions.
  7662.    </P
  7663. ><DIV
  7664. CLASS="note"
  7665. ><BLOCKQUOTE
  7666. CLASS="note"
  7667. ><P
  7668. ><B
  7669. >Important for CGI users: </B
  7670. >
  7671.      Read the <A
  7672. HREF="#faq.installation.forceredirect"
  7673. >faq
  7674.      on cgi.force_redirect</A
  7675. > for important details.  This
  7676.      directive needs to be set to <VAR
  7677. CLASS="literal"
  7678. >0</VAR
  7679. >.
  7680.     </P
  7681. ></BLOCKQUOTE
  7682. ></DIV
  7683. ><DIV
  7684. CLASS="warning"
  7685. ><P
  7686. ></P
  7687. ><TABLE
  7688. CLASS="warning"
  7689. BORDER="1"
  7690. WIDTH="100%"
  7691. ><TR
  7692. ><TD
  7693. ALIGN="CENTER"
  7694. ><B
  7695. >Warning</B
  7696. ></TD
  7697. ></TR
  7698. ><TR
  7699. ><TD
  7700. ALIGN="LEFT"
  7701. ><P
  7702. >By using the CGI setup, your server
  7703. is open to several possible attacks. Please read our
  7704. <A
  7705. HREF="#security.cgi-bin"
  7706. >CGI security section</A
  7707. > to learn how to
  7708. defend yourself from those attacks.</P
  7709. ></TD
  7710. ></TR
  7711. ></TABLE
  7712. ></DIV
  7713. ><DIV
  7714. CLASS="sect2"
  7715. ><HR><H3
  7716. CLASS="sect2"
  7717. ><A
  7718. NAME="install.windows.iis.iis3"
  7719. >Windows and PWS/IIS 3</A
  7720. ></H3
  7721. ><P
  7722. >      The recommended method for configuring these servers is to use
  7723.      the REG file included with the distribution
  7724.      (<TT
  7725. CLASS="filename"
  7726. >pws-php4cgi.reg</TT
  7727. > in the SAPI folder for PHP 4, or
  7728.      <TT
  7729. CLASS="filename"
  7730. >pws-php5cgi.reg</TT
  7731. > in the main folder for PHP 5).
  7732.      You may want to edit this file and make sure
  7733.      the extensions and PHP install directories match your
  7734.      configuration. Or you can follow the steps below to do it
  7735.      manually.
  7736.     </P
  7737. ><DIV
  7738. CLASS="warning"
  7739. ><P
  7740. ></P
  7741. ><TABLE
  7742. CLASS="warning"
  7743. BORDER="1"
  7744. WIDTH="100%"
  7745. ><TR
  7746. ><TD
  7747. ALIGN="CENTER"
  7748. ><B
  7749. >Warning</B
  7750. ></TD
  7751. ></TR
  7752. ><TR
  7753. ><TD
  7754. ALIGN="LEFT"
  7755. ><P
  7756. >       These steps involve working directly with the Windows
  7757.       registry. One error here can leave your system in an unstable
  7758.       state. We highly recommend that you back up your registry
  7759.       first. The PHP Development team will not be held responsible if
  7760.       you damage your registry.
  7761.      </P
  7762. ></TD
  7763. ></TR
  7764. ></TABLE
  7765. ></DIV
  7766. ><P
  7767. >      <P
  7768. ></P
  7769. ><UL
  7770. ><LI
  7771. ><P
  7772. >         Run Regedit.
  7773.        </P
  7774. ></LI
  7775. ><LI
  7776. ><P
  7777. >         Navigate to: <VAR
  7778. CLASS="literal"
  7779. >HKEY_LOCAL_MACHINE /System
  7780.          /CurrentControlSet /Services /W3Svc /Parameters
  7781.          /ScriptMap</VAR
  7782. >.
  7783.        </P
  7784. ></LI
  7785. ><LI
  7786. ><P
  7787. >         On the edit menu select: <VAR
  7788. CLASS="literal"
  7789. >New->String Value</VAR
  7790. >.
  7791.        </P
  7792. ></LI
  7793. ><LI
  7794. ><P
  7795. >         Type in the extension you wish to use for your php
  7796.         scripts. For example <VAR
  7797. CLASS="literal"
  7798. >.php</VAR
  7799. >
  7800.        </P
  7801. ></LI
  7802. ><LI
  7803. ><P
  7804. >         Double click on the new string value and enter the path to
  7805.         <TT
  7806. CLASS="filename"
  7807. >php.exe</TT
  7808. > in the value data field. ex:
  7809.         <TT
  7810. CLASS="filename"
  7811. >C:\php\php.exe</TT
  7812. > for PHP 4, or
  7813.         <TT
  7814. CLASS="filename"
  7815. >C:\php\php-cgi.exe</TT
  7816. > for PHP 5.
  7817.        </P
  7818. ></LI
  7819. ><LI
  7820. ><P
  7821. >         Repeat these steps for each extension you wish to associate
  7822.         with PHP scripts.
  7823.        </P
  7824. ></LI
  7825. ></UL
  7826. >
  7827.     </P
  7828. ><P
  7829. >      The following steps do not affect the web server installation
  7830.      and only apply if you want your PHP scripts to be executed when
  7831.      they are run from the command line (ex. run
  7832.      <TT
  7833. CLASS="filename"
  7834. >C:\myscripts\test.php</TT
  7835. >) or by double clicking
  7836.      on them in a directory viewer window. You may wish to skip these
  7837.      steps as you might prefer the PHP files to load into a text
  7838.      editor when you double click on them.
  7839.     </P
  7840. ><P
  7841. >      <P
  7842. ></P
  7843. ><UL
  7844. ><LI
  7845. ><P
  7846. >         Navigate to: <VAR
  7847. CLASS="literal"
  7848. >HKEY_CLASSES_ROOT</VAR
  7849. >
  7850.        </P
  7851. ></LI
  7852. ><LI
  7853. ><P
  7854. >         On the edit menu select: <VAR
  7855. CLASS="literal"
  7856. >New->Key</VAR
  7857. >.
  7858.        </P
  7859. ></LI
  7860. ><LI
  7861. ><P
  7862. >         Name the key to the extension you setup in the previous
  7863.         section. ex: <VAR
  7864. CLASS="literal"
  7865. >.php</VAR
  7866. >
  7867.        </P
  7868. ></LI
  7869. ><LI
  7870. ><P
  7871. >         Highlight the new key and in the right side pane, double click 
  7872.         the "default value" and enter <VAR
  7873. CLASS="literal"
  7874. >phpfile</VAR
  7875. >.
  7876.        </P
  7877. ></LI
  7878. ><LI
  7879. ><P
  7880. >         Repeat the last step for each extension you set up in the
  7881.         previous section.
  7882.        </P
  7883. ></LI
  7884. ><LI
  7885. ><P
  7886. >         Now create another <VAR
  7887. CLASS="literal"
  7888. >New->Key</VAR
  7889. > under
  7890.         <VAR
  7891. CLASS="literal"
  7892. >HKEY_CLASSES_ROOT</VAR
  7893. > and name it
  7894.         <VAR
  7895. CLASS="literal"
  7896. >phpfile</VAR
  7897. >.
  7898.        </P
  7899. ></LI
  7900. ><LI
  7901. ><P
  7902. >         Highlight the new key <VAR
  7903. CLASS="literal"
  7904. >phpfile</VAR
  7905. > and in the
  7906.         right side pane, double click the "default value" and enter
  7907.         <VAR
  7908. CLASS="literal"
  7909. >PHP Script</VAR
  7910. >.
  7911.        </P
  7912. ></LI
  7913. ><LI
  7914. ><P
  7915. >         Right click on the <VAR
  7916. CLASS="literal"
  7917. >phpfile</VAR
  7918. > key and select
  7919.         <VAR
  7920. CLASS="literal"
  7921. >New->Key</VAR
  7922. >, name it <VAR
  7923. CLASS="literal"
  7924. >Shell</VAR
  7925. >.
  7926.        </P
  7927. ></LI
  7928. ><LI
  7929. ><P
  7930. >         Right click on the <VAR
  7931. CLASS="literal"
  7932. >Shell</VAR
  7933. > key and select
  7934.         <VAR
  7935. CLASS="literal"
  7936. >New->Key</VAR
  7937. >, name it <VAR
  7938. CLASS="literal"
  7939. >open</VAR
  7940. >.
  7941.        </P
  7942. ></LI
  7943. ><LI
  7944. ><P
  7945. >         Right click on the <VAR
  7946. CLASS="literal"
  7947. >open</VAR
  7948. > key and select
  7949.         <VAR
  7950. CLASS="literal"
  7951. >New->Key</VAR
  7952. >, name it
  7953.         <VAR
  7954. CLASS="literal"
  7955. >command</VAR
  7956. >. 
  7957.        </P
  7958. ></LI
  7959. ><LI
  7960. ><P
  7961. >         Highlight the new key <VAR
  7962. CLASS="literal"
  7963. >command</VAR
  7964. > and in the
  7965.         right side pane, double click the "default value" and enter
  7966.         the path to <TT
  7967. CLASS="filename"
  7968. >php.exe</TT
  7969. >. ex:
  7970.         <VAR
  7971. CLASS="literal"
  7972. >c:\php\php.exe -q %1</VAR
  7973. >. (don't forget the
  7974.         <VAR
  7975. CLASS="literal"
  7976. >%1</VAR
  7977. >). 
  7978.        </P
  7979. ></LI
  7980. ><LI
  7981. ><P
  7982. >         Exit Regedit.
  7983.        </P
  7984. ></LI
  7985. ><LI
  7986. ><P
  7987. >         If using PWS on Windows, reboot to reload the registry.
  7988.        </P
  7989. ></LI
  7990. ></UL
  7991. >
  7992.     </P
  7993. ><P
  7994. >      PWS and IIS 3 users now have a fully operational system. IIS 3
  7995.      users can use a nifty <A
  7996. HREF="http://www.genusa.com/iis/iiscfg.html"
  7997. TARGET="_top"
  7998. >tool</A
  7999. >
  8000.      from Steven Genusa to configure their script maps.
  8001.     </P
  8002. ></DIV
  8003. ><DIV
  8004. CLASS="sect2"
  8005. ><HR><H3
  8006. CLASS="sect2"
  8007. ><A
  8008. NAME="install.windows.iis.pws4"
  8009. >Windows and PWS 4 or newer</A
  8010. ></H3
  8011. ><P
  8012. >      When installing PHP on Windows with PWS 4 or newer version,
  8013.      you have two options. One to set up the PHP CGI binary,
  8014.      the other is to use the ISAPI module DLL.
  8015.     </P
  8016. ><P
  8017. >      If you choose the CGI binary, do the following:
  8018.      <P
  8019. ></P
  8020. ><UL
  8021. ><LI
  8022. ><P
  8023. >         Edit the enclosed <TT
  8024. CLASS="filename"
  8025. >pws-php4cgi.reg</TT
  8026. > /
  8027.         <TT
  8028. CLASS="filename"
  8029. >pws-php5cgi.reg</TT
  8030. > file (look into the SAPI folder
  8031.         for PHP 4, or in the main folder for PHP 5) to reflect the location of
  8032.         your <TT
  8033. CLASS="filename"
  8034. >php.exe</TT
  8035. > / <TT
  8036. CLASS="filename"
  8037. >php-cgi.exe</TT
  8038. >.
  8039.         Backslashes should be escaped, for example:
  8040.         <VAR
  8041. CLASS="literal"
  8042. >[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script
  8043.          Map] ".php"="C:\\php\\php.exe"</VAR
  8044. > (change to
  8045.         <VAR
  8046. CLASS="literal"
  8047. >C:\\php\\php-cgi.exe</VAR
  8048. > if you are using PHP 5)
  8049.         Now merge this registery file into your system; you may do 
  8050.         this by double-clicking it.
  8051.        </P
  8052. ></LI
  8053. ><LI
  8054. ><P
  8055. >         In the PWS Manager, right click on a given directory you want
  8056.         to add PHP support to, and select Properties. Check the 'Execute'
  8057.         checkbox, and confirm.
  8058.        </P
  8059. ></LI
  8060. ></UL
  8061. >
  8062.     </P
  8063. ><P
  8064. >      If you choose the ISAPI module, do the following:
  8065.      <P
  8066. ></P
  8067. ><UL
  8068. ><LI
  8069. ><P
  8070. >         Edit the enclosed <TT
  8071. CLASS="filename"
  8072. >pws-php4isapi.reg</TT
  8073. > /
  8074.         <TT
  8075. CLASS="filename"
  8076. >pws-php5isapi.reg</TT
  8077. > file (look into the SAPI folder
  8078.         for PHP 4, or in the main folder for PHP 5) to reflect the location of
  8079.         your <TT
  8080. CLASS="filename"
  8081. >php4isapi.dll</TT
  8082. > /
  8083.         <TT
  8084. CLASS="filename"
  8085. >php5isapi.dll</TT
  8086. >. Backslashes should be escaped, for example:
  8087.         <VAR
  8088. CLASS="literal"
  8089. >[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script
  8090.          Map] ".php"="C:\\php\\sapi\\php4isapi.dll"</VAR
  8091. > (or
  8092.         <VAR
  8093. CLASS="literal"
  8094. >C:\\php\\php5isapi.dll</VAR
  8095. > for PHP 5)
  8096.         Now merge this registery file into your system; you may do 
  8097.         this by double-clicking it.
  8098.        </P
  8099. ></LI
  8100. ><LI
  8101. ><P
  8102. >         In the PWS Manager, right click on a given directory you want to
  8103.         add PHP support to, and select Properties. Check the 'Execute'
  8104.         checkbox, and confirm. 
  8105.        </P
  8106. ></LI
  8107. ></UL
  8108. >
  8109.     </P
  8110. ></DIV
  8111. ><DIV
  8112. CLASS="sect2"
  8113. ><HR><H3
  8114. CLASS="sect2"
  8115. ><A
  8116. NAME="install.windows.iis.iis4"
  8117. >Windows NT/2000/XP and IIS 4 or newer</A
  8118. ></H3
  8119. ><P
  8120. >      To install PHP on an NT/2000/XP Server running IIS 4 or newer,
  8121.      follow these instructions. You have two options to set up
  8122.      PHP, using the CGI binary (<TT
  8123. CLASS="filename"
  8124. >php.exe</TT
  8125. > in PHP 4, or
  8126.      <TT
  8127. CLASS="filename"
  8128. >php-cgi.exe</TT
  8129. > in PHP 5) or with the ISAPI module.
  8130.     </P
  8131. ><P
  8132. >      In either case, you need to start the Microsoft Management
  8133.      Console (may appear as 'Internet Services Manager', either
  8134.      in your Windows NT 4.0 Option Pack branch or the Control
  8135.      Panel=>Administrative Tools under Windows 2000/XP). Then 
  8136.      right click on your Web server node (this will most probably
  8137.      appear as 'Default Web Server'), and select 'Properties'.
  8138.     </P
  8139. ><P
  8140. >      If you want to use the CGI binary, do the following:
  8141.      <P
  8142. ></P
  8143. ><UL
  8144. ><LI
  8145. ><P
  8146. >         Under 'Home Directory', 'Virtual Directory', or
  8147.         'Directory', click on the 'Configuration' button,
  8148.         and then enter the App Mappings tab.
  8149.        </P
  8150. ></LI
  8151. ><LI
  8152. ><P
  8153. >         Click Add, and in the Executable box, type:
  8154.         <VAR
  8155. CLASS="literal"
  8156. >C:\php\php.exe</VAR
  8157. > for PHP 4 or
  8158.         <VAR
  8159. CLASS="literal"
  8160. >C:\php\php-cgi.exe</VAR
  8161. > for PHP 5 (assuming
  8162.         that you have unziped PHP in <TT
  8163. CLASS="filename"
  8164. >c:\php\</TT
  8165. >).
  8166.         </P
  8167. ></LI
  8168. ><LI
  8169. ><P
  8170. >         In the Extension box, type the file name extension you want
  8171.         associated with PHP scripts. Leave 'Method exclusions'
  8172.         blank, and check the 'Script engine' checkbox. You may also
  8173.         like to check the 'check that file exists' box - for a small
  8174.         performance penalty, IIS (or PWS) will check that the script
  8175.         file exists and sort out authentication before firing up PHP.
  8176.         This means that you will get sensible 404 style error messages
  8177.         instead of CGI errors complaining that PHP did not output any data.
  8178.        </P
  8179. ><P
  8180. >         You must start over from the previous step for each
  8181.         extension you want associated with PHP scripts.
  8182.         <VAR
  8183. CLASS="literal"
  8184. >.php</VAR
  8185. > and <VAR
  8186. CLASS="literal"
  8187. >.phtml</VAR
  8188. >
  8189.         are common, although <VAR
  8190. CLASS="literal"
  8191. >.php3</VAR
  8192. > may be
  8193.         required for legacy applications.
  8194.        </P
  8195. ></LI
  8196. ><LI
  8197. ><P
  8198. >         Set up the appropriate security. (This is done in Internet
  8199.         Service Manager), and if your NT Server uses NTFS file system,
  8200.         add execute rights for I_USR_ to the directory that contains
  8201.         <TT
  8202. CLASS="filename"
  8203. >php.exe</TT
  8204. > / <TT
  8205. CLASS="filename"
  8206. >php-cgi.exe</TT
  8207. >.
  8208.        </P
  8209. ></LI
  8210. ></UL
  8211. >
  8212.     </P
  8213. ><P
  8214. >      To use the ISAPI module, do the following:
  8215.      <P
  8216. ></P
  8217. ><UL
  8218. ><LI
  8219. ><P
  8220. >         If you don't want to perform HTTP Authentication using PHP,
  8221.         you can (and should) skip this step. Under ISAPI Filters,
  8222.         add a new ISAPI filter. Use PHP as the filter name, and
  8223.         supply a path to the <TT
  8224. CLASS="filename"
  8225. >php4isapi.dll</TT
  8226. > /
  8227.         <TT
  8228. CLASS="filename"
  8229. >php5isapi.dll</TT
  8230. >.
  8231.        </P
  8232. ></LI
  8233. ><LI
  8234. ><P
  8235. >         Under 'Home Directory', click on the 'Configuration' button.
  8236.         Add a new entry to the Application Mappings. Use the path
  8237.         to the <TT
  8238. CLASS="filename"
  8239. >php4isapi.dll</TT
  8240. > /
  8241.         <TT
  8242. CLASS="filename"
  8243. >php5isapi.dll</TT
  8244. > as the Executable, supply
  8245.         <VAR
  8246. CLASS="literal"
  8247. >.php</VAR
  8248. > as the extension, leave 'Method exclusions'
  8249.         blank, and check the 'Script engine' checkbox.
  8250.        </P
  8251. ></LI
  8252. ><LI
  8253. ><P
  8254. >         Stop IIS completely (NET STOP iisadmin)
  8255.        </P
  8256. ></LI
  8257. ><LI
  8258. ><P
  8259. >         Start IIS again (NET START w3svc)
  8260.        </P
  8261. ></LI
  8262. ></UL
  8263. >
  8264.     </P
  8265. ><P
  8266. >      If you experience 100% CPU usage after some time, turn off the IIS
  8267.      setting <VAR
  8268. CLASS="literal"
  8269. >Cache ISAPI Application</VAR
  8270. >.
  8271.     </P
  8272. ></DIV
  8273. ></DIV
  8274. ><DIV
  8275. CLASS="sect1"
  8276. ><HR><H2
  8277. CLASS="sect1"
  8278. ><A
  8279. NAME="install.windows.apache1"
  8280. >Apache 1.3.x on Microsoft Windows</A
  8281. ></H2
  8282. ><P
  8283. >      This section contains notes and hints specific to Apache 1.3.x installs
  8284.      of PHP on Microsoft Windows systems. There are also
  8285.      <A
  8286. HREF="#install.windows.apache2"
  8287. >instructions and notes
  8288.      for Apache 2</A
  8289. > on a separate page.
  8290.     </P
  8291. ><DIV
  8292. CLASS="note"
  8293. ><BLOCKQUOTE
  8294. CLASS="note"
  8295. ><P
  8296. ><B
  8297. >Note: </B
  8298. >
  8299.       Please read the <A
  8300. HREF="#install.windows.manual"
  8301. >manual
  8302.       installation steps</A
  8303. > first!
  8304.      </P
  8305. ></BLOCKQUOTE
  8306. ></DIV
  8307. ><P
  8308. >      There are two ways to set up PHP to work with Apache 1.3.x
  8309.      on Windows. One is to use the CGI binary (<TT
  8310. CLASS="filename"
  8311. >php.exe</TT
  8312. >
  8313.      for PHP 4 and <TT
  8314. CLASS="filename"
  8315. >php-cgi.exe</TT
  8316. > for PHP 5),
  8317.      the other is to use the Apache Module DLL. In either case
  8318.      you need to edit your <TT
  8319. CLASS="filename"
  8320. >httpd.conf</TT
  8321. > to configure Apache to
  8322.      work with PHP, and then restart the server.
  8323.     </P
  8324. ><P
  8325. >      It is worth noting here that now the SAPI module has been 
  8326.      made more stable under Windows, we recommend it's use above
  8327.      the CGI binary, since it is more transparent and secure.
  8328.     </P
  8329. ><P
  8330. >      Although there can be a few variations of configuring PHP
  8331.      under Apache, these are simple enough to be used by the
  8332.      newcomer. Please consult the Apache Documentation for further
  8333.      configuration directives.
  8334.     </P
  8335. ><P
  8336. >      After changing the configuration file, remember to restart the server, for
  8337.      example, <B
  8338. CLASS="command"
  8339. >NET STOP APACHE</B
  8340. > followed by
  8341.      <B
  8342. CLASS="command"
  8343. >NET START APACHE</B
  8344. >, if you run Apache as a Windows
  8345.      Service, or use your regular shortcuts.
  8346.     </P
  8347. ><DIV
  8348. CLASS="note"
  8349. ><BLOCKQUOTE
  8350. CLASS="note"
  8351. ><P
  8352. ><B
  8353. >Note: </B
  8354. >Remember that when adding
  8355. path values in the Apache configuration files on Windows, all backslashes
  8356. such as <TT
  8357. CLASS="filename"
  8358. >c:\directory\file.ext</TT
  8359. > must be converted to
  8360. forward slashes, as <TT
  8361. CLASS="filename"
  8362. >c:/directory/file.ext</TT
  8363. >.</P
  8364. ></BLOCKQUOTE
  8365. ></DIV
  8366. ><DIV
  8367. CLASS="sect2"
  8368. ><HR><H3
  8369. CLASS="sect2"
  8370. ><A
  8371. NAME="install.windows.apache1.module"
  8372. >Installing as an Apache module</A
  8373. ></H3
  8374. ><P
  8375. >       You should add the following lines to your Apache <TT
  8376. CLASS="filename"
  8377. >httpd.conf</TT
  8378. > file:
  8379.      </P
  8380. ><P
  8381. >       <TABLE
  8382. WIDTH="100%"
  8383. BORDER="0"
  8384. CELLPADDING="0"
  8385. CELLSPACING="0"
  8386. CLASS="EXAMPLE"
  8387. ><TR
  8388. ><TD
  8389. ><DIV
  8390. CLASS="example"
  8391. ><A
  8392. NAME="AEN1374"
  8393. ></A
  8394. ><P
  8395. ><B
  8396. >Example 6-3. PHP as an Apache 1.3.x module</B
  8397. ></P
  8398. ><P
  8399. >          This assumes PHP is installed to <TT
  8400. CLASS="filename"
  8401. >c:\php</TT
  8402. >. Adjust the
  8403.          path if this is not the case.
  8404.         </P
  8405. ><P
  8406. >          For PHP 4:
  8407.         </P
  8408. ><TABLE
  8409. BORDER="0"
  8410. BGCOLOR="#E0E0E0"
  8411. CELLPADDING="5"
  8412. ><TR
  8413. ><TD
  8414. ><PRE
  8415. CLASS="apache-conf"
  8416. ># Add to the end of the LoadModule section
  8417. LoadModule php4_module "c:/php/php4apache.dll"
  8418.  
  8419. # Add to the end of the AddModule section
  8420. AddModule mod_php4.c</PRE
  8421. ></TD
  8422. ></TR
  8423. ></TABLE
  8424. ><P
  8425. >         For PHP 5:
  8426.        </P
  8427. ><TABLE
  8428. BORDER="0"
  8429. BGCOLOR="#E0E0E0"
  8430. CELLPADDING="5"
  8431. ><TR
  8432. ><TD
  8433. ><PRE
  8434. CLASS="apache-conf"
  8435. ># Add to the end of the LoadModule section
  8436. LoadModule php5_module "c:/php/php5apache.dll"
  8437.  
  8438. # Add to the end of the AddModule section
  8439. AddModule mod_php5.c</PRE
  8440. ></TD
  8441. ></TR
  8442. ></TABLE
  8443. ><P
  8444. >         For both:
  8445.        </P
  8446. ><TABLE
  8447. BORDER="0"
  8448. BGCOLOR="#E0E0E0"
  8449. CELLPADDING="5"
  8450. ><TR
  8451. ><TD
  8452. ><PRE
  8453. CLASS="apache-conf"
  8454. ># Add this line inside the <IfModule mod_mime.c> conditional brace
  8455. AddType application/x-httpd-php .php
  8456.  
  8457. # For syntax highlighted .phps files, also add
  8458. AddType application/x-httpd-php-source .phps</PRE
  8459. ></TD
  8460. ></TR
  8461. ></TABLE
  8462. ></DIV
  8463. ></TD
  8464. ></TR
  8465. ></TABLE
  8466. >
  8467.      </P
  8468. ></DIV
  8469. ><DIV
  8470. CLASS="sect2"
  8471. ><HR><H3
  8472. CLASS="sect2"
  8473. ><A
  8474. NAME="install.windows.apache1.cgi"
  8475. >Installing as a CGI binary</A
  8476. ></H3
  8477. ><P
  8478. >       If you unzipped the PHP package to <TT
  8479. CLASS="filename"
  8480. >C:\php\</TT
  8481. > as described
  8482.       in the <A
  8483. HREF="#install.windows.manual"
  8484. >Manual
  8485.       Installation Steps</A
  8486. > section, you need to insert
  8487.       these lines to your Apache configuration file to set
  8488.       up the CGI binary:
  8489.       <TABLE
  8490. WIDTH="100%"
  8491. BORDER="0"
  8492. CELLPADDING="0"
  8493. CELLSPACING="0"
  8494. CLASS="EXAMPLE"
  8495. ><TR
  8496. ><TD
  8497. ><DIV
  8498. CLASS="example"
  8499. ><A
  8500. NAME="AEN1389"
  8501. ></A
  8502. ><P
  8503. ><B
  8504. >Example 6-4. PHP and Apache 1.3.x as CGI</B
  8505. ></P
  8506. ><TABLE
  8507. BORDER="0"
  8508. BGCOLOR="#E0E0E0"
  8509. CELLPADDING="5"
  8510. ><TR
  8511. ><TD
  8512. ><PRE
  8513. CLASS="apache-conf"
  8514. >ScriptAlias /php/ "c:/php/"
  8515. AddType application/x-httpd-php .php
  8516.  
  8517. # For PHP 4
  8518. Action application/x-httpd-php "/php/php.exe"
  8519.  
  8520. # For PHP 5
  8521. Action application/x-httpd-php "/php/php-cgi.exe"
  8522.  
  8523. # specify the directory where php.ini is
  8524. SetEnv PHPRC C:/php</PRE
  8525. ></TD
  8526. ></TR
  8527. ></TABLE
  8528. ></DIV
  8529. ></TD
  8530. ></TR
  8531. ></TABLE
  8532. >
  8533.       Note that the second line in the list above can be found
  8534.       in the actual versions of <TT
  8535. CLASS="filename"
  8536. >httpd.conf</TT
  8537. >, but it is commented out. Remember
  8538.       also to substitute the <TT
  8539. CLASS="filename"
  8540. >c:/php/</TT
  8541. > for your actual path to
  8542.       PHP.
  8543.      </P
  8544. ><DIV
  8545. CLASS="warning"
  8546. ><P
  8547. ></P
  8548. ><TABLE
  8549. CLASS="warning"
  8550. BORDER="1"
  8551. WIDTH="100%"
  8552. ><TR
  8553. ><TD
  8554. ALIGN="CENTER"
  8555. ><B
  8556. >Warning</B
  8557. ></TD
  8558. ></TR
  8559. ><TR
  8560. ><TD
  8561. ALIGN="LEFT"
  8562. ><P
  8563. >By using the CGI setup, your server
  8564. is open to several possible attacks. Please read our
  8565. <A
  8566. HREF="#security.cgi-bin"
  8567. >CGI security section</A
  8568. > to learn how to
  8569. defend yourself from those attacks.</P
  8570. ></TD
  8571. ></TR
  8572. ></TABLE
  8573. ></DIV
  8574. ><P
  8575. >       If you would like to present PHP source files syntax highlighted, there
  8576.       is no such convenient option as with the module version of PHP.
  8577.       If you chose to configure Apache to use PHP as a CGI binary, you
  8578.       will need to use the <A
  8579. HREF="#function.highlight-file"
  8580. ><B
  8581. CLASS="function"
  8582. >highlight_file()</B
  8583. ></A
  8584. > function. To
  8585.       do this simply create a PHP script file and add this code: 
  8586.       <VAR
  8587. CLASS="literal"
  8588. ><?php highlight_file('some_php_script.php'); ?></VAR
  8589. >.
  8590.      </P
  8591. ></DIV
  8592. ></DIV
  8593. ><DIV
  8594. CLASS="sect1"
  8595. ><HR><H2
  8596. CLASS="sect1"
  8597. ><A
  8598. NAME="install.windows.apache2"
  8599. >Apache 2.0.x on Microsoft Windows</A
  8600. ></H2
  8601. ><P
  8602. >      This section contains notes and hints specific to Apache 2.0.x installs
  8603.      of PHP on Microsoft Windows systems. We also
  8604.      have <A
  8605. HREF="#install.windows.apache1"
  8606. >instructions and notes
  8607.      for Apache 1.3.x users on a separate page</A
  8608. >.
  8609.     </P
  8610. ><DIV
  8611. CLASS="note"
  8612. ><BLOCKQUOTE
  8613. CLASS="note"
  8614. ><P
  8615. ><B
  8616. >Note: </B
  8617. >
  8618.       You should read the <A
  8619. HREF="#install.windows.manual"
  8620. >manual
  8621.        installation steps</A
  8622. > first!
  8623.      </P
  8624. ></BLOCKQUOTE
  8625. ></DIV
  8626. ><DIV
  8627. CLASS="warning"
  8628. ><P
  8629. ></P
  8630. ><TABLE
  8631. CLASS="warning"
  8632. BORDER="1"
  8633. WIDTH="100%"
  8634. ><TR
  8635. ><TD
  8636. ALIGN="CENTER"
  8637. ><B
  8638. >Warning</B
  8639. ></TD
  8640. ></TR
  8641. ><TR
  8642. ><TD
  8643. ALIGN="LEFT"
  8644. ><P
  8645. >We do not recommend using a threaded MPM
  8646. in production with Apache2.  Use the prefork MPM instead, or use Apache1.  For information
  8647. on why, read the following 
  8648. <A
  8649. HREF="#faq.installation.apache2"
  8650. >FAQ entry</A
  8651. ></P
  8652. ></TD
  8653. ></TR
  8654. ></TABLE
  8655. ></DIV
  8656. ><P
  8657. >      You are highly encouraged to take a look at the
  8658.      <A
  8659. HREF="http://httpd.apache.org/docs-2.0/"
  8660. TARGET="_top"
  8661. >Apache Documentation</A
  8662. > to get
  8663.      a basic understanding of the Apache 2.0.x Server. Also consider to
  8664.      read the <A
  8665. HREF="http://httpd.apache.org/docs-2.0/platform/windows.html"
  8666. TARGET="_top"
  8667. >Windows specific
  8668.      notes</A
  8669. > for Apache 2.0.x before reading on here.
  8670.     </P
  8671. ><DIV
  8672. CLASS="note"
  8673. ><BLOCKQUOTE
  8674. CLASS="note"
  8675. ><P
  8676. ><B
  8677. >PHP and Apache 2.0.x compatibility notes: </B
  8678. >
  8679.       The following versions of PHP are known to work with the most recent
  8680.       version of Apache 2.0.x:
  8681.       <P
  8682. ></P
  8683. ><UL
  8684. COMPACT="COMPACT"
  8685. ><LI
  8686. ><SPAN
  8687. >          PHP 4.3.0 or later available at
  8688.          <A
  8689. HREF="http://www.php.net/downloads.php"
  8690. TARGET="_top"
  8691. >http://www.php.net/downloads.php</A
  8692. >.
  8693.         </SPAN
  8694. ></LI
  8695. ><LI
  8696. ><SPAN
  8697. >          the latest stable development version.
  8698.          Get the source code <A
  8699. HREF="http://snaps.php.net/php4-latest.tar.gz"
  8700. TARGET="_top"
  8701. >          http://snaps.php.net/php4-latest.tar.gz</A
  8702. > or download binaries
  8703.          for Windows <A
  8704. HREF="http://snaps.php.net/win32/php4-win32-latest.zip"
  8705. TARGET="_top"
  8706. >          http://snaps.php.net/win32/php4-win32-latest.zip</A
  8707. >.
  8708.         </SPAN
  8709. ></LI
  8710. ><LI
  8711. ><SPAN
  8712. >          a prerelease version downloadable from
  8713.          <A
  8714. HREF="http://qa.php.net/"
  8715. TARGET="_top"
  8716. >http://qa.php.net/</A
  8717. >.
  8718.         </SPAN
  8719. ></LI
  8720. ><LI
  8721. ><SPAN
  8722. >          you have always the option to obtain PHP through
  8723.          <A
  8724. HREF="http://www.php.net/anoncvs.php"
  8725. TARGET="_top"
  8726. >anonymous CVS</A
  8727. >.
  8728.         </SPAN
  8729. ></LI
  8730. ></UL
  8731. >
  8732.       These versions of PHP are compatible to Apache 2.0.40 and later.
  8733.      </P
  8734. ><P
  8735. >       Apache 2.0 <VAR
  8736. CLASS="literal"
  8737. >SAPI</VAR
  8738. >-support started with PHP 4.2.0.
  8739.       PHP 4.2.3 works with Apache 2.0.39, don't use any other version of Apache with
  8740.       PHP 4.2.3. However, the recommended setup is to use PHP 4.3.0 or later with
  8741.       the most recent version of Apache2.
  8742.      </P
  8743. ><P
  8744. >       All mentioned versions of PHP will work still with
  8745.       Apache 1.3.x.
  8746.      </P
  8747. ></BLOCKQUOTE
  8748. ></DIV
  8749. ><DIV
  8750. CLASS="warning"
  8751. ><P
  8752. ></P
  8753. ><TABLE
  8754. CLASS="warning"
  8755. BORDER="1"
  8756. WIDTH="100%"
  8757. ><TR
  8758. ><TD
  8759. ALIGN="CENTER"
  8760. ><B
  8761. >Warning</B
  8762. ></TD
  8763. ></TR
  8764. ><TR
  8765. ><TD
  8766. ALIGN="LEFT"
  8767. ><P
  8768. >       Apache 2.0.x is designed to run on Windows NT 4.0, Windows 2000 or
  8769.       Windows XP. At this time, support for Windows 9x is incomplete.
  8770.       Apache 2.0.x is not expected to work on those platforms at this time.
  8771.      </P
  8772. ></TD
  8773. ></TR
  8774. ></TABLE
  8775. ></DIV
  8776. ><P
  8777. >      Download the most recent version of <A
  8778. HREF="http://www.apache.org/"
  8779. TARGET="_top"
  8780. >      Apache 2.0.x</A
  8781. > and a fitting PHP version.
  8782.      Follow the <A
  8783. HREF="#install.windows.manual"
  8784. >Manual Installation
  8785.      Steps</A
  8786. > and come back to go on with the integration of PHP and Apache.
  8787.     </P
  8788. ><P
  8789. >      There are two ways to set up PHP to work with Apache 2.0.x on Windows.
  8790.      One is to use the CGI binary the other is to use the Apache module DLL.
  8791.      In either case you need to edit your <TT
  8792. CLASS="filename"
  8793. >httpd.conf</TT
  8794. > to configure Apache
  8795.      to work with PHP and then restart the server.
  8796.     </P
  8797. ><DIV
  8798. CLASS="note"
  8799. ><BLOCKQUOTE
  8800. CLASS="note"
  8801. ><P
  8802. ><B
  8803. >Note: </B
  8804. >Remember that when adding
  8805. path values in the Apache configuration files on Windows, all backslashes
  8806. such as <TT
  8807. CLASS="filename"
  8808. >c:\directory\file.ext</TT
  8809. > must be converted to
  8810. forward slashes, as <TT
  8811. CLASS="filename"
  8812. >c:/directory/file.ext</TT
  8813. >.</P
  8814. ></BLOCKQUOTE
  8815. ></DIV
  8816. ><DIV
  8817. CLASS="sect2"
  8818. ><HR><H3
  8819. CLASS="sect2"
  8820. ><A
  8821. NAME="install.windows.apache2.cgi"
  8822. >Installing as a CGI binary</A
  8823. ></H3
  8824. ><P
  8825. >       You need to insert these three lines to your Apache <TT
  8826. CLASS="filename"
  8827. >httpd.conf</TT
  8828. >
  8829.       configuration file to set up the CGI binary:
  8830.       <TABLE
  8831. WIDTH="100%"
  8832. BORDER="0"
  8833. CELLPADDING="0"
  8834. CELLSPACING="0"
  8835. CLASS="EXAMPLE"
  8836. ><TR
  8837. ><TD
  8838. ><DIV
  8839. CLASS="example"
  8840. ><A
  8841. NAME="AEN1448"
  8842. ></A
  8843. ><P
  8844. ><B
  8845. >Example 6-5. PHP and Apache 2.0 as CGI</B
  8846. ></P
  8847. ><TABLE
  8848. BORDER="0"
  8849. BGCOLOR="#E0E0E0"
  8850. CELLPADDING="5"
  8851. ><TR
  8852. ><TD
  8853. ><PRE
  8854. CLASS="apache-conf"
  8855. >ScriptAlias /php/ "c:/php/"
  8856. AddType application/x-httpd-php .php
  8857.  
  8858. # For PHP 4
  8859. Action application/x-httpd-php "/php/php.exe"
  8860.  
  8861. # For PHP 5
  8862. Action application/x-httpd-php "/php/php-cgi.exe"</PRE
  8863. ></TD
  8864. ></TR
  8865. ></TABLE
  8866. ></DIV
  8867. ></TD
  8868. ></TR
  8869. ></TABLE
  8870. >
  8871.      </P
  8872. ><DIV
  8873. CLASS="warning"
  8874. ><P
  8875. ></P
  8876. ><TABLE
  8877. CLASS="warning"
  8878. BORDER="1"
  8879. WIDTH="100%"
  8880. ><TR
  8881. ><TD
  8882. ALIGN="CENTER"
  8883. ><B
  8884. >Warning</B
  8885. ></TD
  8886. ></TR
  8887. ><TR
  8888. ><TD
  8889. ALIGN="LEFT"
  8890. ><P
  8891. >By using the CGI setup, your server
  8892. is open to several possible attacks. Please read our
  8893. <A
  8894. HREF="#security.cgi-bin"
  8895. >CGI security section</A
  8896. > to learn how to
  8897. defend yourself from those attacks.</P
  8898. ></TD
  8899. ></TR
  8900. ></TABLE
  8901. ></DIV
  8902. ></DIV
  8903. ><DIV
  8904. CLASS="sect2"
  8905. ><HR><H3
  8906. CLASS="sect2"
  8907. ><A
  8908. NAME="install.windows.apache2.module"
  8909. >Installing as an Apache module</A
  8910. ></H3
  8911. ><P
  8912. >       You need to insert these two lines to your
  8913.       Apache <TT
  8914. CLASS="filename"
  8915. >httpd.conf</TT
  8916. > configuration file to set up the
  8917.       PHP module for Apache 2.0:
  8918.       <TABLE
  8919. WIDTH="100%"
  8920. BORDER="0"
  8921. CELLPADDING="0"
  8922. CELLSPACING="0"
  8923. CLASS="EXAMPLE"
  8924. ><TR
  8925. ><TD
  8926. ><DIV
  8927. CLASS="example"
  8928. ><A
  8929. NAME="AEN1458"
  8930. ></A
  8931. ><P
  8932. ><B
  8933. >Example 6-6. PHP and Apache 2.0 as Module</B
  8934. ></P
  8935. ><TABLE
  8936. BORDER="0"
  8937. BGCOLOR="#E0E0E0"
  8938. CELLPADDING="5"
  8939. ><TR
  8940. ><TD
  8941. ><PRE
  8942. CLASS="apache-conf"
  8943. ># For PHP 4 do something like this:
  8944. LoadModule php4_module "c:/php/php4apache2.dll"
  8945. AddType application/x-httpd-php .php
  8946.  
  8947. # For PHP 5 do something like this:
  8948. LoadModule php5_module "c:/php/php5apache2.dll"
  8949. AddType application/x-httpd-php .php
  8950.  
  8951. # configure the path to php.ini
  8952. PHPIniDir "C:/php"</PRE
  8953. ></TD
  8954. ></TR
  8955. ></TABLE
  8956. ></DIV
  8957. ></TD
  8958. ></TR
  8959. ></TABLE
  8960. >
  8961.      </P
  8962. ><DIV
  8963. CLASS="note"
  8964. ><BLOCKQUOTE
  8965. CLASS="note"
  8966. ><P
  8967. ><B
  8968. >Note: </B
  8969. >
  8970.        Remember to substitute the <TT
  8971. CLASS="filename"
  8972. >c:/php/</TT
  8973. > for your actual
  8974.        path to PHP in the above examples. Take care to use
  8975.        either <TT
  8976. CLASS="filename"
  8977. >php4apache2.dll</TT
  8978. > or 
  8979.        <TT
  8980. CLASS="filename"
  8981. >php5apache2.dll</TT
  8982. > in your LoadModule directive and
  8983.        <SPAN
  8984. CLASS="emphasis"
  8985. ><I
  8986. CLASS="emphasis"
  8987. >not</I
  8988. ></SPAN
  8989. > <TT
  8990. CLASS="filename"
  8991. >php4apache.dll</TT
  8992. > or 
  8993.        <TT
  8994. CLASS="filename"
  8995. >php5apache.dll</TT
  8996. > as the latter ones are designed to
  8997.        run with <A
  8998. HREF="#install.windows.apache1"
  8999. >Apache 1.3.x</A
  9000. >.
  9001.       </P
  9002. ></BLOCKQUOTE
  9003. ></DIV
  9004. ><DIV
  9005. CLASS="note"
  9006. ><BLOCKQUOTE
  9007. CLASS="note"
  9008. ><P
  9009. ><B
  9010. >Note: </B
  9011. >
  9012.        If you want to use content negotiation, read
  9013.        <A
  9014. HREF="#faq.installation.apache.multiviews"
  9015. >related FAQ</A
  9016. >.
  9017.       </P
  9018. ></BLOCKQUOTE
  9019. ></DIV
  9020. ><DIV
  9021. CLASS="warning"
  9022. ><P
  9023. ></P
  9024. ><TABLE
  9025. CLASS="warning"
  9026. BORDER="1"
  9027. WIDTH="100%"
  9028. ><TR
  9029. ><TD
  9030. ALIGN="CENTER"
  9031. ><B
  9032. >Warning</B
  9033. ></TD
  9034. ></TR
  9035. ><TR
  9036. ><TD
  9037. ALIGN="LEFT"
  9038. ><P
  9039. >        Don't mix up your installation with DLL files from
  9040.        <SPAN
  9041. CLASS="emphasis"
  9042. ><I
  9043. CLASS="emphasis"
  9044. >different PHP versions</I
  9045. ></SPAN
  9046. >. You have the only choice
  9047.        to use the DLL's and extensions that ship with your downloaded PHP version.
  9048.       </P
  9049. ></TD
  9050. ></TR
  9051. ></TABLE
  9052. ></DIV
  9053. ></DIV
  9054. ></DIV
  9055. ><DIV
  9056. CLASS="sect1"
  9057. ><HR><H2
  9058. CLASS="sect1"
  9059. ><A
  9060. NAME="install.windows.sun"
  9061. >Sun, iPlanet and Netscape servers on Microsoft Windows</A
  9062. ></H2
  9063. ><P
  9064. >     This section contains notes and hints specific to Sun Java System Web Server,
  9065.     Sun ONE Web Server, iPlanet and Netscape server installs of PHP on Windows.
  9066.    </P
  9067. ><P
  9068. >     From PHP 4.3.3 on you can use PHP scripts with the
  9069.     <A
  9070. HREF="#ref.nsapi"
  9071. >NSAPI module</A
  9072. > to 
  9073.     <A
  9074. HREF="#install.windows.sun.specialpages"
  9075. >generate custom
  9076.     directory listings and error pages</A
  9077. >. Additional functions for
  9078.     Apache compatibility are also available. For support in current webservers
  9079.     read the <A
  9080. HREF="#install.windows.sun.notes"
  9081. >note about
  9082.     subrequests</A
  9083. >.
  9084.    </P
  9085. ><DIV
  9086. CLASS="sect2"
  9087. ><HR><H3
  9088. CLASS="sect2"
  9089. ><A
  9090. NAME="install.windows.sun.cgi"
  9091. >CGI setup on Sun, iPlanet and Netscape servers</A
  9092. ></H3
  9093. ><P
  9094. >      To install PHP as a CGI handler, do the following:
  9095.     </P
  9096. ><P
  9097. ></P
  9098. ><UL
  9099. ><LI
  9100. ><P
  9101. >        Copy <TT
  9102. CLASS="filename"
  9103. >php4ts.dll</TT
  9104. > to your systemroot
  9105.        (the directory where you installed Windows)
  9106.       </P
  9107. ></LI
  9108. ><LI
  9109. ><P
  9110. >        Make a file association from the command line.
  9111.        Type the following two lines:
  9112.        <TABLE
  9113. BORDER="0"
  9114. BGCOLOR="#E0E0E0"
  9115. CELLPADDING="5"
  9116. ><TR
  9117. ><TD
  9118. ><PRE
  9119. CLASS="shell"
  9120. >assoc .php=PHPScript
  9121. ftype PHPScript=c:\php\php.exe %1 %*</PRE
  9122. ></TD
  9123. ></TR
  9124. ></TABLE
  9125. >
  9126.       </P
  9127. ></LI
  9128. ><LI
  9129. ><P
  9130. >        In the Netscape Enterprise Administration Server create
  9131.        a dummy shellcgi directory and remove it just after (this
  9132.        step creates 5 important lines in obj.conf and allow the
  9133.        web server to handle shellcgi scripts).
  9134.       </P
  9135. ></LI
  9136. ><LI
  9137. ><P
  9138. >        In the Netscape Enterprise Administration Server create
  9139.        a new mime type (Category: type,
  9140.        Content-Type: magnus-internal/shellcgi, File Suffix:php).
  9141.       </P
  9142. ></LI
  9143. ><LI
  9144. ><P
  9145. >        Do it for each web server instance you want PHP to run
  9146.       </P
  9147. ></LI
  9148. ></UL
  9149. ><P
  9150. >      More details about setting up
  9151.      PHP as a CGI executable can be found here:
  9152.      <A
  9153. HREF="http://benoit.noss.free.fr/php/install-php.html"
  9154. TARGET="_top"
  9155. >http://benoit.noss.free.fr/php/install-php.html</A
  9156. >
  9157.     </P
  9158. ></DIV
  9159. ><DIV
  9160. CLASS="sect2"
  9161. ><HR><H3
  9162. CLASS="sect2"
  9163. ><A
  9164. NAME="install.windows.sun.nsapi"
  9165. >NSAPI setup on Sun, iPlanet and Netscape servers</A
  9166. ></H3
  9167. ><P
  9168. >      To install PHP with NSAPI, do the following:
  9169.     </P
  9170. ><P
  9171. ></P
  9172. ><UL
  9173. ><LI
  9174. ><P
  9175. >        Copy <TT
  9176. CLASS="filename"
  9177. >php4ts.dll</TT
  9178. > to your systemroot
  9179.        (the directory where you installed Windows)
  9180.       </P
  9181. ></LI
  9182. ><LI
  9183. ><P
  9184. >        Make a file association from the command line.
  9185.        Type the following two lines:
  9186.        <TABLE
  9187. BORDER="0"
  9188. BGCOLOR="#E0E0E0"
  9189. CELLPADDING="5"
  9190. ><TR
  9191. ><TD
  9192. ><PRE
  9193. CLASS="shell"
  9194. >assoc .php=PHPScript
  9195. ftype PHPScript=c:\php\php.exe %1 %*</PRE
  9196. ></TD
  9197. ></TR
  9198. ></TABLE
  9199. >
  9200.       </P
  9201. ></LI
  9202. ><LI
  9203. ><P
  9204. >        In the Netscape Enterprise Administration Server create
  9205.        a new mime type (Category: type,
  9206.        Content-Type: magnus-internal/x-httpd-php, File Suffix: php).
  9207.       </P
  9208. ></LI
  9209. ><LI
  9210. ><P
  9211. >         Edit <TT
  9212. CLASS="filename"
  9213. >magnus.conf</TT
  9214. > (for servers >= 6) or
  9215.         <TT
  9216. CLASS="filename"
  9217. >obj.conf</TT
  9218. > (for servers < 6) and add the following:
  9219.         You should
  9220.         place the lines after <VAR
  9221. CLASS="literal"
  9222. >mime types init</VAR
  9223. >.
  9224.        <TABLE
  9225. BORDER="0"
  9226. BGCOLOR="#E0E0E0"
  9227. CELLPADDING="5"
  9228. ><TR
  9229. ><TD
  9230. ><PRE
  9231. CLASS="programlisting"
  9232. >Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll"
  9233. Init fn="php4_init" LateInit="yes" errorString="Failed to initialise PHP!" [php_ini="c:/path/to/php.ini"]</PRE
  9234. ></TD
  9235. ></TR
  9236. ></TABLE
  9237. >
  9238.        (PHP >= 4.3.3) The <VAR
  9239. CLASS="literal"
  9240. >php_ini</VAR
  9241. > parameter is
  9242.        optional but with it you can place your
  9243.        <TT
  9244. CLASS="filename"
  9245. >php.ini</TT
  9246. > in your webserver config directory.
  9247.       </P
  9248. ></LI
  9249. ><LI
  9250. ><P
  9251. >        Configure the default object in <TT
  9252. CLASS="filename"
  9253. >obj.conf</TT
  9254. >
  9255.        (for virtual server classes [Sun Web Server 6.0+] in
  9256.        their <TT
  9257. CLASS="filename"
  9258. >vserver.obj.conf</TT
  9259. >):
  9260.        In the <VAR
  9261. CLASS="literal"
  9262. ><Object name="default"></VAR
  9263. >
  9264.        section, place this line necessarily after all 'ObjectType'
  9265.        and before all 'AddLog' lines:
  9266.        <TABLE
  9267. BORDER="0"
  9268. BGCOLOR="#E0E0E0"
  9269. CELLPADDING="5"
  9270. ><TR
  9271. ><TD
  9272. ><PRE
  9273. CLASS="programlisting"
  9274. >Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...]</PRE
  9275. ></TD
  9276. ></TR
  9277. ></TABLE
  9278. >
  9279.        (PHP >= 4.3.3) As additional parameters you can add some special
  9280.        <TT
  9281. CLASS="filename"
  9282. >php.ini</TT
  9283. >-values, for example you
  9284.        can set a <VAR
  9285. CLASS="literal"
  9286. >docroot="/path/to/docroot"</VAR
  9287. >
  9288.        specific to the context <VAR
  9289. CLASS="literal"
  9290. >php4_execute</VAR
  9291. >
  9292.        is called. For boolean ini-keys please use 0/1 as value,
  9293.        not <VAR
  9294. CLASS="literal"
  9295. >"On","Off",...</VAR
  9296. >
  9297.        (this will not work correctly), e.g.
  9298.        <VAR
  9299. CLASS="literal"
  9300. >zlib.output_compression=1</VAR
  9301. > instead of
  9302.        <VAR
  9303. CLASS="literal"
  9304. >zlib.output_compression="On"</VAR
  9305. >
  9306.       </P
  9307. ></LI
  9308. ><LI
  9309. ><P
  9310. >        This is only needed if you want to configure a directory that only consists of
  9311.        PHP scripts (same like a cgi-bin directory):
  9312.        <TABLE
  9313. BORDER="0"
  9314. BGCOLOR="#E0E0E0"
  9315. CELLPADDING="5"
  9316. ><TR
  9317. ><TD
  9318. ><PRE
  9319. CLASS="programlisting"
  9320. ><Object name="x-httpd-php">
  9321. ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
  9322. Service fn=php4_execute [inikey=value inikey=value ...]
  9323. </Object></PRE
  9324. ></TD
  9325. ></TR
  9326. ></TABLE
  9327. >
  9328.        After that you can configure a directory in the Administration server and assign it
  9329.        the style <VAR
  9330. CLASS="literal"
  9331. >x-httpd-php</VAR
  9332. >. All files in it will get executed as PHP.
  9333.        This is nice to hide PHP usage by renaming files to <TT
  9334. CLASS="filename"
  9335. >.html</TT
  9336. >.
  9337.       </P
  9338. ></LI
  9339. ><LI
  9340. ><P
  9341. >        Restart your web service and apply changes
  9342.       </P
  9343. ></LI
  9344. ><LI
  9345. ><P
  9346. >        Do it for each web server instance you want PHP to run
  9347.       </P
  9348. ></LI
  9349. ></UL
  9350. ><DIV
  9351. CLASS="note"
  9352. ><BLOCKQUOTE
  9353. CLASS="note"
  9354. ><P
  9355. ><B
  9356. >Note: </B
  9357. >
  9358.       More details about setting up
  9359.       PHP as an NSAPI filter can be found here:
  9360.       <A
  9361. HREF="http://benoit.noss.free.fr/php/install-php4.html"
  9362. TARGET="_top"
  9363. >http://benoit.noss.free.fr/php/install-php4.html</A
  9364. >
  9365.      </P
  9366. ></BLOCKQUOTE
  9367. ></DIV
  9368. ><DIV
  9369. CLASS="note"
  9370. ><BLOCKQUOTE
  9371. CLASS="note"
  9372. ><P
  9373. ><B
  9374. >Note: </B
  9375. >
  9376.       The stacksize that PHP uses depends on the configuration of the webserver. If you get
  9377.       crashes with very large PHP scripts, it is recommended to raise it with the Admin Server
  9378.       (in the section "MAGNUS EDITOR").
  9379.      </P
  9380. ></BLOCKQUOTE
  9381. ></DIV
  9382. ></DIV
  9383. ><DIV
  9384. CLASS="sect2"
  9385. ><HR><H3
  9386. CLASS="sect2"
  9387. ><A
  9388. NAME="install.windows.sun.phpini"
  9389. >CGI environment and recommended modifications in php.ini</A
  9390. ></H3
  9391. ><P
  9392. >      Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE
  9393.      WS/iPlanet/Netscape is a multithreaded web server. Because of that all
  9394.      requests are running in the same process space (the space of the webserver
  9395.      itself) and this space has only one environment. If you want to get CGI
  9396.      variables like <VAR
  9397. CLASS="literal"
  9398. >PATH_INFO</VAR
  9399. >, <VAR
  9400. CLASS="literal"
  9401. >HTTP_HOST</VAR
  9402. >
  9403.      etc. it is not the correct way to try this in the old PHP 3.x way with
  9404.      <A
  9405. HREF="#function.getenv"
  9406. ><B
  9407. CLASS="function"
  9408. >getenv()</B
  9409. ></A
  9410. > or a similar way (register globals to
  9411.      environment, <VAR
  9412. CLASS="literal"
  9413. >$_ENV</VAR
  9414. >). You would only get the environment
  9415.      of the running webserver without any valid CGI variables!
  9416.     </P
  9417. ><DIV
  9418. CLASS="note"
  9419. ><BLOCKQUOTE
  9420. CLASS="note"
  9421. ><P
  9422. ><B
  9423. >Note: </B
  9424. >
  9425.       Why are there (invalid) CGI variables in the environment?
  9426.      </P
  9427. ><P
  9428. >       Answer: This is because you started the webserver process from the admin server
  9429.       which runs the startup script of the webserver, you wanted to start, as a CGI script
  9430.       (a CGI script inside of the admin server!). This is why the environment of
  9431.       the started webserver has some CGI environment variables in it. You can test
  9432.       this by starting the webserver not from the administration server. Use
  9433.       the command line as root user and start it manually - you will see
  9434.       there are no CGI-like environment variables.
  9435.      </P
  9436. ></BLOCKQUOTE
  9437. ></DIV
  9438. ><P
  9439. >      Simply change your scripts to get CGI variables in the correct way for
  9440.      PHP 4.x by using the superglobal <VAR
  9441. CLASS="literal"
  9442. >$_SERVER</VAR
  9443. >. If you have
  9444.      older scripts which use <VAR
  9445. CLASS="literal"
  9446. >$HTTP_HOST</VAR
  9447. >, etc., you should turn
  9448.      on <VAR
  9449. CLASS="literal"
  9450. >register_globals</VAR
  9451. > in <TT
  9452. CLASS="filename"
  9453. >php.ini</TT
  9454. > and change the variable
  9455.      order too (important: remove <VAR
  9456. CLASS="literal"
  9457. >"E"</VAR
  9458. > from it,
  9459.      because you do not need the environment here):
  9460.      <TABLE
  9461. BORDER="0"
  9462. BGCOLOR="#E0E0E0"
  9463. CELLPADDING="5"
  9464. ><TR
  9465. ><TD
  9466. ><PRE
  9467. CLASS="programlisting"
  9468. >variables_order = "GPCS"
  9469. register_globals = On</PRE
  9470. ></TD
  9471. ></TR
  9472. ></TABLE
  9473. >
  9474.     </P
  9475. ></DIV
  9476. ><DIV
  9477. CLASS="sect2"
  9478. ><HR><H3
  9479. CLASS="sect2"
  9480. ><A
  9481. NAME="install.windows.sun.specialpages"
  9482. >Special use for error pages or self-made directory listings (PHP >= 4.3.3)</A
  9483. ></H3
  9484. ><P
  9485. >      You can use PHP to generate the error pages for <VAR
  9486. CLASS="literal"
  9487. >"404 Not Found"</VAR
  9488. >
  9489.      or similar. Add the following line to the object in <TT
  9490. CLASS="filename"
  9491. >obj.conf</TT
  9492. > for
  9493.      every error page you want to overwrite:
  9494.      <TABLE
  9495. BORDER="0"
  9496. BGCOLOR="#E0E0E0"
  9497. CELLPADDING="5"
  9498. ><TR
  9499. ><TD
  9500. ><PRE
  9501. CLASS="programlisting"
  9502. >Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]</PRE
  9503. ></TD
  9504. ></TR
  9505. ></TABLE
  9506. >
  9507.      where <VAR
  9508. CLASS="literal"
  9509. >XXX</VAR
  9510. > is the HTTP error code. Please delete
  9511.      any other <VAR
  9512. CLASS="literal"
  9513. >Error</VAR
  9514. > directives which could interfere with yours.
  9515.      If you want to place a page for all errors that could exist, leave
  9516.      the <VAR
  9517. CLASS="literal"
  9518. >code</VAR
  9519. > parameter out. Your script can get the HTTP status code
  9520.      with <VAR
  9521. CLASS="literal"
  9522. >$_SERVER['ERROR_TYPE']</VAR
  9523. >.
  9524.     </P
  9525. ><P
  9526. >      Another possibility is to generate self-made directory listings.
  9527.      Just create a PHP script which displays a directory listing and
  9528.      replace the corresponding default Service line for
  9529.      <VAR
  9530. CLASS="literal"
  9531. >type="magnus-internal/directory"</VAR
  9532. >
  9533.      in <TT
  9534. CLASS="filename"
  9535. >obj.conf</TT
  9536. > with the following:
  9537.      <TABLE
  9538. BORDER="0"
  9539. BGCOLOR="#E0E0E0"
  9540. CELLPADDING="5"
  9541. ><TR
  9542. ><TD
  9543. ><PRE
  9544. CLASS="programlisting"
  9545. >Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]</PRE
  9546. ></TD
  9547. ></TR
  9548. ></TABLE
  9549. >
  9550.      For both error and directory listing pages the original URI and
  9551.      translated URI are in the variables <VAR
  9552. CLASS="literal"
  9553. >$_SERVER['PATH_INFO']</VAR
  9554. > and
  9555.      <VAR
  9556. CLASS="literal"
  9557. >$_SERVER['PATH_TRANSLATED']</VAR
  9558. >.
  9559.     </P
  9560. ></DIV
  9561. ><DIV
  9562. CLASS="sect2"
  9563. ><HR><H3
  9564. CLASS="sect2"
  9565. ><A
  9566. NAME="install.windows.sun.notes"
  9567. >Note about <A
  9568. HREF="#function.nsapi-virtual"
  9569. ><B
  9570. CLASS="function"
  9571. >nsapi_virtual()</B
  9572. ></A
  9573. > and subrequests (PHP >= 4.3.3)</A
  9574. ></H3
  9575. ><P
  9576. >      The NSAPI module now supports the <A
  9577. HREF="#function.nsapi-virtual"
  9578. ><B
  9579. CLASS="function"
  9580. >nsapi_virtual()</B
  9581. ></A
  9582. > function
  9583.      (alias: <A
  9584. HREF="#function.virtual"
  9585. ><B
  9586. CLASS="function"
  9587. >virtual()</B
  9588. ></A
  9589. >)
  9590.      to make subrequests on the webserver and insert the result in the webpage.
  9591.      The problem is, that this function uses some undocumented features from
  9592.      the NSAPI library.
  9593.     </P
  9594. ><P
  9595. >      Under Unix this is not a problem, because the module automatically looks
  9596.      for the needed functions and uses them if available.
  9597.      If not, <A
  9598. HREF="#function.nsapi-virtual"
  9599. ><B
  9600. CLASS="function"
  9601. >nsapi_virtual()</B
  9602. ></A
  9603. > is disabled.
  9604.     </P
  9605. ><P
  9606. >      Under Windows limitations in the DLL handling need the use of a automatic
  9607.      detection of the most recent <TT
  9608. CLASS="filename"
  9609. >ns-httpdXX.dll</TT
  9610. > file.
  9611.      This is tested for servers till version 6.1. If a newer version of the
  9612.      Sun server is used, the detection fails and <A
  9613. HREF="#function.nsapi-virtual"
  9614. ><B
  9615. CLASS="function"
  9616. >nsapi_virtual()</B
  9617. ></A
  9618. >
  9619.      is disabled.
  9620.     </P
  9621. ><P
  9622. >      If this is the case, try the following:
  9623.      Add the following parameter to <VAR
  9624. CLASS="literal"
  9625. >php4_init</VAR
  9626. > in
  9627.      <TT
  9628. CLASS="filename"
  9629. >magnus.conf</TT
  9630. >/<TT
  9631. CLASS="filename"
  9632. >obj.conf</TT
  9633. >:
  9634.      <TABLE
  9635. BORDER="0"
  9636. BGCOLOR="#E0E0E0"
  9637. CELLPADDING="5"
  9638. ><TR
  9639. ><TD
  9640. ><PRE
  9641. CLASS="programlisting"
  9642. >Init fn=php4_init ... server_lib="ns-httpdXX.dll"</PRE
  9643. ></TD
  9644. ></TR
  9645. ></TABLE
  9646. >
  9647.      where <VAR
  9648. CLASS="literal"
  9649. >XX</VAR
  9650. > is the correct DLL version number.
  9651.      To get it, look in the server-root for the correct DLL name. The
  9652.      DLL with the biggest filesize is the right one.
  9653.     </P
  9654. ><P
  9655. >      You can check the status by using the <A
  9656. HREF="#function.phpinfo"
  9657. ><B
  9658. CLASS="function"
  9659. >phpinfo()</B
  9660. ></A
  9661. > function.
  9662.     </P
  9663. ><DIV
  9664. CLASS="note"
  9665. ><BLOCKQUOTE
  9666. CLASS="note"
  9667. ><P
  9668. ><B
  9669. >Note: </B
  9670. >
  9671.       But be warned: Support for <A
  9672. HREF="#function.nsapi-virtual"
  9673. ><B
  9674. CLASS="function"
  9675. >nsapi_virtual()</B
  9676. ></A
  9677. > is EXPERIMENTAL!!!
  9678.      </P
  9679. ></BLOCKQUOTE
  9680. ></DIV
  9681. ></DIV
  9682. ></DIV
  9683. ><DIV
  9684. CLASS="sect1"
  9685. ><HR><H2
  9686. CLASS="sect1"
  9687. ><A
  9688. NAME="install.windows.omnihttpd"
  9689. >OmniHTTPd Server</A
  9690. ></H2
  9691. ><P
  9692. >     This section contains notes and hints specific to
  9693.     <A
  9694. HREF="http://www.omnicron.ca/"
  9695. TARGET="_top"
  9696. >OmniHTTPd</A
  9697. > on Windows.
  9698.    </P
  9699. ><DIV
  9700. CLASS="note"
  9701. ><BLOCKQUOTE
  9702. CLASS="note"
  9703. ><P
  9704. ><B
  9705. >Note: </B
  9706. >
  9707.      You should read the <A
  9708. HREF="#install.windows.manual"
  9709. >manual
  9710.      installation steps</A
  9711. > first!
  9712.     </P
  9713. ></BLOCKQUOTE
  9714. ></DIV
  9715. ><DIV
  9716. CLASS="warning"
  9717. ><P
  9718. ></P
  9719. ><TABLE
  9720. CLASS="warning"
  9721. BORDER="1"
  9722. WIDTH="100%"
  9723. ><TR
  9724. ><TD
  9725. ALIGN="CENTER"
  9726. ><B
  9727. >Warning</B
  9728. ></TD
  9729. ></TR
  9730. ><TR
  9731. ><TD
  9732. ALIGN="LEFT"
  9733. ><P
  9734. >By using the CGI setup, your server
  9735. is open to several possible attacks. Please read our
  9736. <A
  9737. HREF="#security.cgi-bin"
  9738. >CGI security section</A
  9739. > to learn how to
  9740. defend yourself from those attacks.</P
  9741. ></TD
  9742. ></TR
  9743. ></TABLE
  9744. ></DIV
  9745. ><P
  9746. >     You need to complete the following steps to make PHP
  9747.     work with OmniHTTPd. This is a CGI executable setup.
  9748.     SAPI is supported by OmniHTTPd, but some tests have shown
  9749.     that it is not so stable to use PHP as an ISAPI module.
  9750.    </P
  9751. ><DIV
  9752. CLASS="note"
  9753. ><BLOCKQUOTE
  9754. CLASS="note"
  9755. ><P
  9756. ><B
  9757. >Important for CGI users: </B
  9758. >
  9759.      Read the <A
  9760. HREF="#faq.installation.forceredirect"
  9761. >faq
  9762.      on cgi.force_redirect</A
  9763. > for important details.  This
  9764.      directive needs to be set to <VAR
  9765. CLASS="literal"
  9766. >0</VAR
  9767. >.
  9768.     </P
  9769. ></BLOCKQUOTE
  9770. ></DIV
  9771. ><P
  9772. >     <P
  9773. ></P
  9774. ><OL
  9775. TYPE="1"
  9776. ><LI
  9777. ><P
  9778. >        Install OmniHTTPd server.
  9779.       </P
  9780. ></LI
  9781. ><LI
  9782. ><P
  9783. >        Right click on the blue OmniHTTPd icon in the system
  9784.        tray and select <VAR
  9785. CLASS="literal"
  9786. >Properties</VAR
  9787. >
  9788.       </P
  9789. ></LI
  9790. ><LI
  9791. ><P
  9792. >        Click on <VAR
  9793. CLASS="literal"
  9794. >Web Server Global Settings</VAR
  9795. >
  9796.       </P
  9797. ></LI
  9798. ><LI
  9799. ><P
  9800. >        On the 'External' tab, enter: <VAR
  9801. CLASS="literal"
  9802. >virtual = .php
  9803.         | actual = c:\php\php.exe</VAR
  9804. > (use
  9805.        <TT
  9806. CLASS="filename"
  9807. >php-cgi.exe</TT
  9808. > if installing PHP 5), and use the Add
  9809.        button.
  9810.       </P
  9811. ></LI
  9812. ><LI
  9813. ><P
  9814. >        On the <VAR
  9815. CLASS="literal"
  9816. >Mime</VAR
  9817. > tab, enter:
  9818.        <VAR
  9819. CLASS="literal"
  9820. >virtual = wwwserver/stdcgi | actual = .php</VAR
  9821. >,
  9822.        and use the Add button.
  9823.       </P
  9824. ></LI
  9825. ><LI
  9826. ><P
  9827. >        Click <VAR
  9828. CLASS="literal"
  9829. >OK</VAR
  9830. >
  9831.       </P
  9832. ></LI
  9833. ></OL
  9834. >
  9835.    </P
  9836. ><P
  9837. >     Repeat steps 2 - 6 for each extension you want to associate with PHP.
  9838.    </P
  9839. ><DIV
  9840. CLASS="note"
  9841. ><BLOCKQUOTE
  9842. CLASS="note"
  9843. ><P
  9844. ><B
  9845. >Note: </B
  9846. >
  9847.      Some OmniHTTPd packages come with built in PHP support.
  9848.      You can choose at setup time to do a custom setup, and
  9849.      uncheck the PHP component. We recommend you to use the latest
  9850.      PHP binaries. Some OmniHTTPd servers come with PHP 4 beta
  9851.      distributions, so you should choose not to set up
  9852.      the built in support, but install your own. If the server
  9853.      is already on your machine, use the Replace button in Step
  9854.      4 and 5 to set the new, correct information.
  9855.     </P
  9856. ></BLOCKQUOTE
  9857. ></DIV
  9858. ></DIV
  9859. ><DIV
  9860. CLASS="sect1"
  9861. ><HR><H2
  9862. CLASS="sect1"
  9863. ><A
  9864. NAME="install.windows.sambar"
  9865. >Sambar Server on Microsoft Windows</A
  9866. ></H2
  9867. ><P
  9868. >      This section contains notes and hints specific to the
  9869.      <A
  9870. HREF="http://www.sambar.com/"
  9871. TARGET="_top"
  9872. >Sambar Server</A
  9873. > for Windows.
  9874.     </P
  9875. ><DIV
  9876. CLASS="note"
  9877. ><BLOCKQUOTE
  9878. CLASS="note"
  9879. ><P
  9880. ><B
  9881. >Note: </B
  9882. >
  9883.       You should read the <A
  9884. HREF="#install.windows.manual"
  9885. >manual
  9886.        installation steps</A
  9887. > first!
  9888.      </P
  9889. ></BLOCKQUOTE
  9890. ></DIV
  9891. ><P
  9892. >      This list describes how to set up the ISAPI module to
  9893.      work with the Sambar server on Windows.
  9894.     </P
  9895. ><P
  9896. >      <P
  9897. ></P
  9898. ><UL
  9899. ><LI
  9900. ><P
  9901. >         Find the file called <TT
  9902. CLASS="filename"
  9903. >mappings.ini</TT
  9904. > (in the config
  9905.         directory) in the Sambar install directory.
  9906.        </P
  9907. ></LI
  9908. ><LI
  9909. ><P
  9910. >         Open <TT
  9911. CLASS="filename"
  9912. >mappings.ini</TT
  9913. > and add the following line
  9914.         under <VAR
  9915. CLASS="literal"
  9916. >[ISAPI]</VAR
  9917. >:
  9918.       <TABLE
  9919. WIDTH="100%"
  9920. BORDER="0"
  9921. CELLPADDING="0"
  9922. CELLSPACING="0"
  9923. CLASS="EXAMPLE"
  9924. ><TR
  9925. ><TD
  9926. ><DIV
  9927. CLASS="example"
  9928. ><A
  9929. NAME="AEN1659"
  9930. ></A
  9931. ><P
  9932. ><B
  9933. >Example 6-7. ISAPI configuration of Sambar</B
  9934. ></P
  9935. ><TABLE
  9936. BORDER="0"
  9937. BGCOLOR="#E0E0E0"
  9938. CELLPADDING="5"
  9939. ><TR
  9940. ><TD
  9941. ><PRE
  9942. CLASS="programlisting"
  9943. >#for PHP 4
  9944. *.php = c:\php\php4isapi.dll
  9945.  
  9946. #for PHP 5
  9947. *.php = c:\php\php5isapi.dll</PRE
  9948. ></TD
  9949. ></TR
  9950. ></TABLE
  9951. ></DIV
  9952. ></TD
  9953. ></TR
  9954. ></TABLE
  9955. >
  9956.         (This line assumes that PHP was installed in
  9957.         <TT
  9958. CLASS="filename"
  9959. >c:\php</TT
  9960. >.)
  9961.        </P
  9962. ></LI
  9963. ><LI
  9964. ><P
  9965. >         Now restart the Sambar server for the changes to take effect.
  9966.        </P
  9967. ></LI
  9968. ></UL
  9969. >
  9970.     </P
  9971. ></DIV
  9972. ><DIV
  9973. CLASS="sect1"
  9974. ><HR><H2
  9975. CLASS="sect1"
  9976. ><A
  9977. NAME="install.windows.xitami"
  9978. >Xitami on Microsoft Windows</A
  9979. ></H2
  9980. ><P
  9981. >      This section contains notes and hints specific to
  9982.      <A
  9983. HREF="http://www.xitami.com/"
  9984. TARGET="_top"
  9985. >Xitami</A
  9986. > on Windows.
  9987.     </P
  9988. ><DIV
  9989. CLASS="note"
  9990. ><BLOCKQUOTE
  9991. CLASS="note"
  9992. ><P
  9993. ><B
  9994. >Note: </B
  9995. >
  9996.       You should read the <A
  9997. HREF="#install.windows.manual"
  9998. >manual
  9999.        installation steps</A
  10000. > first!
  10001.      </P
  10002. ></BLOCKQUOTE
  10003. ></DIV
  10004. ><P
  10005. >      This list describes how to set up the PHP CGI binary
  10006.      to work with Xitami on Windows.
  10007.     </P
  10008. ><DIV
  10009. CLASS="note"
  10010. ><BLOCKQUOTE
  10011. CLASS="note"
  10012. ><P
  10013. ><B
  10014. >Important for CGI users: </B
  10015. >
  10016.       Read the <A
  10017. HREF="#faq.installation.forceredirect"
  10018. >faq
  10019.       on cgi.force_redirect</A
  10020. > for important details.  This
  10021.       directive needs to be set to <VAR
  10022. CLASS="literal"
  10023. >0</VAR
  10024. >.
  10025.       If you want to use <VAR
  10026. CLASS="literal"
  10027. >$_SERVER['PHP_SELF']</VAR
  10028. > you have to
  10029.       enable the <A
  10030. HREF="#ini.cgi.fix-pathinfo"
  10031. >cgi.fix_pathinfo</A
  10032. >
  10033.       directive.
  10034.      </P
  10035. ></BLOCKQUOTE
  10036. ></DIV
  10037. ><DIV
  10038. CLASS="warning"
  10039. ><P
  10040. ></P
  10041. ><TABLE
  10042. CLASS="warning"
  10043. BORDER="1"
  10044. WIDTH="100%"
  10045. ><TR
  10046. ><TD
  10047. ALIGN="CENTER"
  10048. ><B
  10049. >Warning</B
  10050. ></TD
  10051. ></TR
  10052. ><TR
  10053. ><TD
  10054. ALIGN="LEFT"
  10055. ><P
  10056. >By using the CGI setup, your server
  10057. is open to several possible attacks. Please read our
  10058. <A
  10059. HREF="#security.cgi-bin"
  10060. >CGI security section</A
  10061. > to learn how to
  10062. defend yourself from those attacks.</P
  10063. ></TD
  10064. ></TR
  10065. ></TABLE
  10066. ></DIV
  10067. ><P
  10068. >      <P
  10069. ></P
  10070. ><UL
  10071. ><LI
  10072. ><P
  10073. >         Make sure the webserver is running, and point
  10074.         your browser to xitamis admin console
  10075.         (usually <VAR
  10076. CLASS="literal"
  10077. >http://127.0.0.1/admin</VAR
  10078. >),
  10079.         and click on Configuration.
  10080.        </P
  10081. ></LI
  10082. ><LI
  10083. ><P
  10084. >         Navigate to the Filters, and put the
  10085.         extension which PHP should parse (i.e. .php)
  10086.         into the field File extensions (.xxx).
  10087.        </P
  10088. ></LI
  10089. ><LI
  10090. ><P
  10091. >         In Filter command or script put the path and name
  10092.         of your PHP CGI executable i.e. <TT
  10093. CLASS="filename"
  10094. >C:\php\php.exe</TT
  10095. >
  10096.         for PHP 4, or <TT
  10097. CLASS="filename"
  10098. >C:\php\php-cgi.exe</TT
  10099. > for PHP 5.
  10100.        </P
  10101. ></LI
  10102. ><LI
  10103. ><P
  10104. >         Press the 'Save' icon.
  10105.        </P
  10106. ></LI
  10107. ><LI
  10108. ><P
  10109. >         Restart the server to reflect changes.
  10110.        </P
  10111. ></LI
  10112. ></UL
  10113. >
  10114.     </P
  10115. ></DIV
  10116. ><DIV
  10117. CLASS="sect1"
  10118. ><HR><H2
  10119. CLASS="sect1"
  10120. ><A
  10121. NAME="install.windows.building"
  10122. >Building from source</A
  10123. ></H2
  10124. ><P
  10125. >      Before getting started, it is worthwhile answering the question:
  10126.      "Why is building on Windows so hard?" Two reasons come to mind:
  10127.     </P
  10128. ><P
  10129. ></P
  10130. ><OL
  10131. TYPE="1"
  10132. ><LI
  10133. ><P
  10134. >        Windows does not (yet) enjoy a large community of developers
  10135.        who are willing to freely share their source. As a direct
  10136.        result, the necessary investment in infrastructure required
  10137.        to support such development hasn't been made. By and large,
  10138.        what is available has been made possible by the porting of
  10139.        necessary utilities from Unix. Don't be surprised if some of
  10140.        this heritage shows through from time to time.
  10141.       </P
  10142. ></LI
  10143. ><LI
  10144. ><P
  10145. >        Pretty much all of the instructions that follow are of the
  10146.        "set and forget" variety. So sit back and try follow the
  10147.        instructions below as faithfully as you can.
  10148.       </P
  10149. ></LI
  10150. ></OL
  10151. ><DIV
  10152. CLASS="sect2"
  10153. ><HR><H3
  10154. CLASS="sect2"
  10155. ><A
  10156. NAME="install.windows.building.requirement"
  10157. >Requirements</A
  10158. ></H3
  10159. ><P
  10160. >       To compile and build PHP you need a Microsoft
  10161.       Development Environment. Microsoft Visual C++ 6.0 is recommended.
  10162.       To extract the downloaded files you need a extraction utility
  10163.       (e.g.: Winzip). If you don't already have an unzip utility, you
  10164.       can get a free version from <A
  10165. HREF="http://www.info-zip.org/pub/infozip/"
  10166. TARGET="_top"
  10167. >InfoZip</A
  10168. >.
  10169.      </P
  10170. ><P
  10171. >       Before you get started, you have to download...
  10172.      </P
  10173. ><P
  10174. ></P
  10175. ><UL
  10176. ><LI
  10177. ><P
  10178. >         ..the win32 buildtools from the PHP site
  10179.         at <A
  10180. HREF="http://www.php.net/extra/win32build.zip"
  10181. TARGET="_top"
  10182. >http://www.php.net/extra/win32build.zip</A
  10183. >.
  10184.        </P
  10185. ></LI
  10186. ><LI
  10187. ><P
  10188. >         ..the source code for the DNS name resolver used by PHP from
  10189.         <A
  10190. HREF="http://www.php.net/extra/bindlib_w32.zip"
  10191. TARGET="_top"
  10192. >         http://www.php.net/extra/bindlib_w32.zip</A
  10193. >. This is a replacement for the 
  10194.         <TT
  10195. CLASS="filename"
  10196. >resolv.lib</TT
  10197. > library included in <TT
  10198. CLASS="filename"
  10199. >         win32build.zip</TT
  10200. >.
  10201.        </P
  10202. ></LI
  10203. ><LI
  10204. ><P
  10205. >         If you plan to compile PHP as a Apache
  10206.         module you will also need the <A
  10207. HREF="http://www.apache.org/dist/httpd/"
  10208. TARGET="_top"
  10209. >Apache
  10210.         sources</A
  10211. >.
  10212.        </P
  10213. ></LI
  10214. ></UL
  10215. ><P
  10216. >       Finally, you are going to need the source to PHP itself. You can get
  10217.       the latest development version using <A
  10218. HREF="http://www.php.net/anoncvs.php"
  10219. TARGET="_top"
  10220. >       anonymous CVS</A
  10221. >, a <A
  10222. HREF="http://snaps.php.net/"
  10223. TARGET="_top"
  10224. >       snapshot</A
  10225. > or the most recent released <A
  10226. HREF="http://www.php.net/downloads.php"
  10227. TARGET="_top"
  10228. >       source</A
  10229. > tarball.
  10230.      </P
  10231. ></DIV
  10232. ><DIV
  10233. CLASS="sect2"
  10234. ><HR><H3
  10235. CLASS="sect2"
  10236. ><A
  10237. NAME="install.windows.building.install"
  10238. >Putting it all together</A
  10239. ></H3
  10240. ><P
  10241. >       After downloading the required packages you have to extract them in a
  10242.       proper place.
  10243.       <P
  10244. ></P
  10245. ><UL
  10246. ><LI
  10247. ><P
  10248. >          Create a working directory where all files end up after extracting, e.g:
  10249.          <TT
  10250. CLASS="filename"
  10251. >C:\work</TT
  10252. >.
  10253.         </P
  10254. ></LI
  10255. ><LI
  10256. ><P
  10257. >          Create the directory <TT
  10258. CLASS="filename"
  10259. >win32build</TT
  10260. > under your
  10261.          working directory (<TT
  10262. CLASS="filename"
  10263. >C:\work</TT
  10264. >) and unzip <TT
  10265. CLASS="filename"
  10266. >          win32build.zip</TT
  10267. > into it.
  10268.         </P
  10269. ></LI
  10270. ><LI
  10271. ><P
  10272. >          Create the directory <TT
  10273. CLASS="filename"
  10274. >bindlib_w32</TT
  10275. > under your
  10276.          working directory (<TT
  10277. CLASS="filename"
  10278. >C:\work</TT
  10279. >) and unzip <TT
  10280. CLASS="filename"
  10281. >          bindlib_w32.zip</TT
  10282. > into it.
  10283.         </P
  10284. ></LI
  10285. ><LI
  10286. ><P
  10287. >          Extract the downloaded PHP source code into your working directory
  10288.          (<TT
  10289. CLASS="filename"
  10290. >C:\work</TT
  10291. >).
  10292.         </P
  10293. ></LI
  10294. ></UL
  10295. >
  10296.       Following this steps your directory structure looks like this:
  10297.       <DIV
  10298. CLASS="informalexample"
  10299. ><P
  10300. ></P
  10301. ><A
  10302. NAME="AEN1747"
  10303. ></A
  10304. ><TABLE
  10305. BORDER="0"
  10306. BGCOLOR="#E0E0E0"
  10307. CELLPADDING="5"
  10308. ><TR
  10309. ><TD
  10310. ><PRE
  10311. CLASS="programlisting"
  10312. >+--c:\work
  10313. |  |
  10314. |  +--bindlib_w32
  10315. |  |  |
  10316. |  |  +--arpa
  10317. |  |  |
  10318. |  |  +--conf
  10319. |  |  |
  10320. |  |  +--...
  10321. |  |
  10322. |  +--php-4.x.x
  10323. |  |  |
  10324. |  |  +--build
  10325. |  |  |
  10326. |  |  +--...
  10327. |  |  |
  10328. |  |  +--win32
  10329. |  |  |
  10330. |  |  +--...
  10331. |  |
  10332. |  +--win32build
  10333. |  |  |
  10334. |  |  +--bin
  10335. |  |  |
  10336. |  |  +--include
  10337. |  |  |
  10338. |  |  +--lib</PRE
  10339. ></TD
  10340. ></TR
  10341. ></TABLE
  10342. ><P
  10343. ></P
  10344. ></DIV
  10345. >
  10346.       Create the directories <TT
  10347. CLASS="filename"
  10348. >c:\usr\local\lib</TT
  10349. >. Copy
  10350.       <TT
  10351. CLASS="filename"
  10352. >bison.simple</TT
  10353. > from <TT
  10354. CLASS="filename"
  10355. >c:\work\win32build\bin
  10356.       </TT
  10357. > to <TT
  10358. CLASS="filename"
  10359. >c:\usr\local\lib</TT
  10360. >.
  10361.      </P
  10362. ><DIV
  10363. CLASS="note"
  10364. ><BLOCKQUOTE
  10365. CLASS="note"
  10366. ><P
  10367. ><B
  10368. >Note: </B
  10369. >
  10370.        <A
  10371. HREF="http://www.cygwin.com/"
  10372. TARGET="_top"
  10373. >Cygwin</A
  10374. > users may omit the last
  10375.        step. A properly installed Cygwin environment provides the mandatory
  10376.        files <TT
  10377. CLASS="filename"
  10378. >bison.simple</TT
  10379. > and
  10380.        <TT
  10381. CLASS="filename"
  10382. >bison.exe</TT
  10383. >.
  10384.       </P
  10385. ></BLOCKQUOTE
  10386. ></DIV
  10387. ></DIV
  10388. ><DIV
  10389. CLASS="sect2"
  10390. ><HR><H3
  10391. CLASS="sect2"
  10392. ><A
  10393. NAME="install.windows.building.configure"
  10394. >Configure MVC ++</A
  10395. ></H3
  10396. ><P
  10397. >        The next step is to configure MVC ++ to prepare for compiling.
  10398.        Launch Microsoft Visual C++, and from the menu select
  10399.        Tools => Options. In the dialog, select the
  10400.        directories tab. Sequentially change the dropdown
  10401.        to Executables, Includes, and Library files. Your entries should look
  10402.        like this:
  10403.        <P
  10404. ></P
  10405. ><UL
  10406. ><LI
  10407. ><P
  10408. >           Executable files: <TT
  10409. CLASS="filename"
  10410. >c:\work\win32build\bin</TT
  10411. >,
  10412.           Cygwin users: <TT
  10413. CLASS="filename"
  10414. >cygwin\bin</TT
  10415. >
  10416.          </P
  10417. ></LI
  10418. ><LI
  10419. ><P
  10420. >           Include files: <TT
  10421. CLASS="filename"
  10422. >c:\work\win32build\include</TT
  10423. >
  10424.          </P
  10425. ></LI
  10426. ><LI
  10427. ><P
  10428. >           Library files: <TT
  10429. CLASS="filename"
  10430. >c:\work\win32build\lib</TT
  10431. >
  10432.          </P
  10433. ></LI
  10434. ></UL
  10435. >
  10436.       </P
  10437. ></DIV
  10438. ><DIV
  10439. CLASS="sect2"
  10440. ><HR><H3
  10441. CLASS="sect2"
  10442. ><A
  10443. NAME="install.windows.building.resolvlib"
  10444. >Build resolv.lib</A
  10445. ></H3
  10446. ><P
  10447. >        You must build the <TT
  10448. CLASS="filename"
  10449. >resolv.lib</TT
  10450. > library.
  10451.        Decide whether you want to have debug symbols available
  10452.        (bindlib - Win32 Debug) or not (bindlib - Win32 Release).
  10453.        Build the appropriate configuration: 
  10454.        <P
  10455. ></P
  10456. ><UL
  10457. ><LI
  10458. ><P
  10459. >           For GUI users, launch VC++, and then select File => Open
  10460.           Workspace, navigate to <TT
  10461. CLASS="filename"
  10462. >c:\work\bindlib_w32</TT
  10463. > and
  10464.           select <TT
  10465. CLASS="filename"
  10466. >bindlib.dsw</TT
  10467. >. Then select Build=>Set
  10468.           Active Configuration and select the desired configuration.
  10469.           Finally select Build=>Rebuild All.
  10470.          </P
  10471. ></LI
  10472. ><LI
  10473. ><P
  10474. >           For command line users, make sure that you either have the C++
  10475.           environment variables registered, or have run
  10476.           <B
  10477. CLASS="command"
  10478. >vcvars.bat</B
  10479. >, and then execute one of the following
  10480.           commands:
  10481.          </P
  10482. ><P
  10483. ></P
  10484. ><UL
  10485. ><LI
  10486. ><P
  10487. >             <KBD
  10488. CLASS="userinput"
  10489. >msdev bindlib.dsp /MAKE "bindlib - Win32 Debug"</KBD
  10490. >
  10491.            </P
  10492. ></LI
  10493. ><LI
  10494. ><P
  10495. >             <KBD
  10496. CLASS="userinput"
  10497. >msdev bindlib.dsp /MAKE "bindlib - Win32 Release"</KBD
  10498. >
  10499.            </P
  10500. ></LI
  10501. ></UL
  10502. ></LI
  10503. ></UL
  10504. >
  10505.        At this point, you should have a usable <TT
  10506. CLASS="filename"
  10507. >resolv.lib</TT
  10508. >
  10509.        in either your <TT
  10510. CLASS="filename"
  10511. >c:\work\bindlib_w32\Debug</TT
  10512. > or
  10513.        <TT
  10514. CLASS="filename"
  10515. >Release</TT
  10516. > subdirectories. Copy this file into your
  10517.        <TT
  10518. CLASS="filename"
  10519. >c:\work\win32build\lib</TT
  10520. > directory over the file
  10521.        by the same name found in there.
  10522.       </P
  10523. ></DIV
  10524. ><DIV
  10525. CLASS="sect2"
  10526. ><HR><H3
  10527. CLASS="sect2"
  10528. ><A
  10529. NAME="install.windows.building.compile"
  10530. >Compiling</A
  10531. ></H3
  10532. ><P
  10533. >       The best way to get started is to build the CGI version.
  10534.      </P
  10535. ><P
  10536. ></P
  10537. ><UL
  10538. ><LI
  10539. ><P
  10540. >         For GUI users, launch VC++, and then select File => Open
  10541.         Workspace and select <TT
  10542. CLASS="filename"
  10543. >c:\work\php-4.x.x\win32\php4ts.dsw
  10544.         </TT
  10545. >. Then select Build=>Set Active
  10546.         Configuration and select the desired configuration, either
  10547.         <VAR
  10548. CLASS="literal"
  10549. >php4ts - Win32 Debug_TS</VAR
  10550. > or
  10551.         <VAR
  10552. CLASS="literal"
  10553. >php4ts - Win32 Release_TS</VAR
  10554. >. Finally select
  10555.         Build=>Rebuild All.
  10556.        </P
  10557. ></LI
  10558. ><LI
  10559. ><P
  10560. >         For command line users, make sure that you either have
  10561.         the C++ environment variables registered, or have run
  10562.         <B
  10563. CLASS="command"
  10564. >vcvars.bat</B
  10565. >, and then execute one of the
  10566.         following commands from the <TT
  10567. CLASS="filename"
  10568. >c:\work\php-4.x.x\win32
  10569.         </TT
  10570. > directory:
  10571.        </P
  10572. ><P
  10573. ></P
  10574. ><UL
  10575. ><LI
  10576. ><P
  10577. >           <KBD
  10578. CLASS="userinput"
  10579. >msdev php4ts.dsp /MAKE "php4ts - Win32 Debug_TS"</KBD
  10580. >
  10581.          </P
  10582. ></LI
  10583. ><LI
  10584. ><P
  10585. >           <KBD
  10586. CLASS="userinput"
  10587. >msdev php4ts.dsp /MAKE "php4ts - Win32 Release_TS"</KBD
  10588. >
  10589.          </P
  10590. ></LI
  10591. ><LI
  10592. ><P
  10593. >           At this point, you should have a usable <TT
  10594. CLASS="filename"
  10595. >php.exe</TT
  10596. >
  10597.           in either your <TT
  10598. CLASS="filename"
  10599. >c:\work\php-4.x.x.\Debug_TS</TT
  10600. > or
  10601.           <TT
  10602. CLASS="filename"
  10603. >Release_TS</TT
  10604. > subdirectories.
  10605.          </P
  10606. ></LI
  10607. ></UL
  10608. ></LI
  10609. ></UL
  10610. ><P
  10611. >       It is possible to do minor customization to the build process by editing
  10612.       the <TT
  10613. CLASS="filename"
  10614. >main/config.win32.h</TT
  10615. > file. For example you can
  10616.       change the default location of <TT
  10617. CLASS="filename"
  10618. >php.ini</TT
  10619. >, the built-in extensions, and the
  10620.       default location for your extensions.
  10621.      </P
  10622. ><P
  10623. >       Next you may want to build the CLI version which is designed to use
  10624.       <A
  10625. HREF="#features.commandline"
  10626. >PHP from the command line</A
  10627. >.
  10628.       The steps are the same as for building the CGI version, except you have
  10629.       to select the <VAR
  10630. CLASS="literal"
  10631. >php4ts_cli - Win32 Debug_TS</VAR
  10632. > or
  10633.       <VAR
  10634. CLASS="literal"
  10635. >php4ts_cli - Win32 Release_TS</VAR
  10636. > project file. After a
  10637.       successful compiling run you will find the <TT
  10638. CLASS="filename"
  10639. >php.exe</TT
  10640. >
  10641.       in either the directory <TT
  10642. CLASS="filename"
  10643. >Release_TS\cli\</TT
  10644. > or
  10645.       <TT
  10646. CLASS="filename"
  10647. >Debug_TS\cli\</TT
  10648. >.
  10649.      </P
  10650. ><DIV
  10651. CLASS="note"
  10652. ><BLOCKQUOTE
  10653. CLASS="note"
  10654. ><P
  10655. ><B
  10656. >Note: </B
  10657. >
  10658.        If you want to use PEAR and the comfortable command line installer,
  10659.        the CLI-SAPI is mandatory. For more information about PEAR and the
  10660.        installer read the documentation at the <A
  10661. HREF="http://pear.php.net/manual/"
  10662. TARGET="_top"
  10663. >        PEAR</A
  10664. > website.
  10665.       </P
  10666. ></BLOCKQUOTE
  10667. ></DIV
  10668. ><P
  10669. >       In order to build the SAPI module (<TT
  10670. CLASS="filename"
  10671. >php4isapi.dll</TT
  10672. >)
  10673.       for integrating PHP with Microsoft IIS, set your active configuration to
  10674.       <TT
  10675. CLASS="filename"
  10676. >php4isapi-whatever-config</TT
  10677. > and build the desired dll.
  10678.      </P
  10679. ></DIV
  10680. ></DIV
  10681. ><DIV
  10682. CLASS="sect1"
  10683. ><HR><H2
  10684. CLASS="sect1"
  10685. ><A
  10686. NAME="install.windows.extensions"
  10687. >Installation of extensions on Windows</A
  10688. ></H2
  10689. ><P
  10690. >      After installing PHP and a webserver on Windows, you will probably want to
  10691.      install some extensions for added functionality. You can choose which
  10692.      extensions you would like to load when PHP starts by modifying your
  10693.      <TT
  10694. CLASS="filename"
  10695. >php.ini</TT
  10696. >. You can also load a module dynamically in your script using
  10697.      <A
  10698. HREF="#function.dl"
  10699. ><B
  10700. CLASS="function"
  10701. >dl()</B
  10702. ></A
  10703. >.
  10704.     </P
  10705. ><P
  10706. >      The DLLs for PHP extensions are prefixed with <VAR
  10707. CLASS="literal"
  10708. >php_</VAR
  10709. >.
  10710.     </P
  10711. ><DIV
  10712. CLASS="note"
  10713. ><BLOCKQUOTE
  10714. CLASS="note"
  10715. ><P
  10716. ><B
  10717. >Note: </B
  10718. >
  10719.       In PHP 4.3.1 BCMath, Calendar, COM, Ctype, FTP, MySQL, ODBC, Overload,
  10720.       PCRE, Session, Tokenizer, WDDX, XML and Zlib support is
  10721.       <SPAN
  10722. CLASS="emphasis"
  10723. ><I
  10724. CLASS="emphasis"
  10725. >built in</I
  10726. ></SPAN
  10727. >. You don't need to load any additional
  10728.       extensions in order to use these functions. See your distributions
  10729.       <TT
  10730. CLASS="filename"
  10731. >README.txt</TT
  10732. > or <TT
  10733. CLASS="filename"
  10734. >install.txt</TT
  10735. >
  10736.       or <A
  10737. HREF="#install.windows.extensions.overview"
  10738. >this table</A
  10739. >
  10740.       for a list of built in modules.
  10741.      </P
  10742. ></BLOCKQUOTE
  10743. ></DIV
  10744. ><P
  10745. >      The default location PHP searches for extensions is
  10746.      <TT
  10747. CLASS="filename"
  10748. >c:\php4\extensions</TT
  10749. > in PHP 4 and
  10750.      <TT
  10751. CLASS="filename"
  10752. >c:\php5</TT
  10753. > in PHP 5. To change this
  10754.      setting to reflect your setup of PHP edit your <TT
  10755. CLASS="filename"
  10756. >php.ini</TT
  10757. > file:
  10758.      <P
  10759. ></P
  10760. ><UL
  10761. ><LI
  10762. ><P
  10763. >         You will need to change the
  10764.         <A
  10765. HREF="#ini.extension-dir"
  10766. >extension_dir</A
  10767. > setting to
  10768.         point to the directory where your extensions lives, or where you have
  10769.         placed your <TT
  10770. CLASS="filename"
  10771. >php_*.dll</TT
  10772. > files. Please do not
  10773.         forget the last backslash. For example:
  10774.         <DIV
  10775. CLASS="informalexample"
  10776. ><P
  10777. ></P
  10778. ><A
  10779. NAME="AEN1858"
  10780. ></A
  10781. ><TABLE
  10782. BORDER="0"
  10783. BGCOLOR="#E0E0E0"
  10784. CELLPADDING="5"
  10785. ><TR
  10786. ><TD
  10787. ><PRE
  10788. CLASS="ini"
  10789. >extension_dir = c:/php/extensions/</PRE
  10790. ></TD
  10791. ></TR
  10792. ></TABLE
  10793. ><P
  10794. ></P
  10795. ></DIV
  10796. >
  10797.        </P
  10798. ></LI
  10799. ><LI
  10800. ><P
  10801. >        Enable the extension(s) in <TT
  10802. CLASS="filename"
  10803. >php.ini</TT
  10804. > you want to use by uncommenting the
  10805.        <VAR
  10806. CLASS="literal"
  10807. >extension=php_*.dll</VAR
  10808. > lines in <TT
  10809. CLASS="filename"
  10810. >php.ini</TT
  10811. >. This is done
  10812.        by deleting the leading ; form the extension you want to load. 
  10813.        <TABLE
  10814. WIDTH="100%"
  10815. BORDER="0"
  10816. CELLPADDING="0"
  10817. CELLSPACING="0"
  10818. CLASS="EXAMPLE"
  10819. ><TR
  10820. ><TD
  10821. ><DIV
  10822. CLASS="example"
  10823. ><A
  10824. NAME="AEN1865"
  10825. ></A
  10826. ><P
  10827. ><B
  10828. >Example 6-8. Enable <A
  10829. HREF="#ref.bzip2"
  10830. >Bzip2</A
  10831. > extension for PHP-Windows</B
  10832. ></P
  10833. ><TABLE
  10834. BORDER="0"
  10835. BGCOLOR="#E0E0E0"
  10836. CELLPADDING="5"
  10837. ><TR
  10838. ><TD
  10839. ><PRE
  10840. CLASS="ini"
  10841. >// change the following line from ...
  10842. ;extension=php_bz2.dll
  10843.  
  10844. // ... to
  10845. extension=php_bz2.dll</PRE
  10846. ></TD
  10847. ></TR
  10848. ></TABLE
  10849. ></DIV
  10850. ></TD
  10851. ></TR
  10852. ></TABLE
  10853. >      
  10854.        </P
  10855. ></LI
  10856. ><LI
  10857. ><P
  10858. >         Some of the extensions need extra DLLs to work. Couple of them can be
  10859.         found in the distribution package, in the
  10860.         <TT
  10861. CLASS="filename"
  10862. >C:\php\dlls\</TT
  10863. > folder in PHP 4 or
  10864.         in the main folder in PHP 5, but some, for example Oracle
  10865.         (<TT
  10866. CLASS="filename"
  10867. >php_oci8.dll</TT
  10868. >) require DLLs which are not bundled
  10869.         with the distribution package. If you are installing PHP 4, copy the
  10870.         bundled DLLs from <TT
  10871. CLASS="filename"
  10872. >C:\php\dlls</TT
  10873. >
  10874.         folder to the main <TT
  10875. CLASS="filename"
  10876. >C:\php</TT
  10877. >
  10878.         folder. Don't forget to include <TT
  10879. CLASS="filename"
  10880. >C:\php</TT
  10881. > in the system
  10882.         <VAR
  10883. CLASS="varname"
  10884. >PATH</VAR
  10885. > (this process is explained in a separate <A
  10886. HREF="#faq.installation.addtopath"
  10887. >FAQ entry</A
  10888. >).
  10889.        </P
  10890. ></LI
  10891. ></UL
  10892. >
  10893.    <DIV
  10894. CLASS="note"
  10895. ><BLOCKQUOTE
  10896. CLASS="note"
  10897. ><P
  10898. ><B
  10899. >Note: </B
  10900. >
  10901.      If you are running a server module version of PHP
  10902.      remember to restart your webserver to reflect your changes to <TT
  10903. CLASS="filename"
  10904. >php.ini</TT
  10905. >.
  10906.     </P
  10907. ></BLOCKQUOTE
  10908. ></DIV
  10909. >
  10910.    </P
  10911. ><P
  10912. >     The following table describes some of the extensions available and required
  10913.     additional dlls.   
  10914.     <DIV
  10915. CLASS="table"
  10916. ><A
  10917. NAME="install.windows.extensions.overview"
  10918. ></A
  10919. ><P
  10920. ><B
  10921. >Table 6-1. PHP Extensions</B
  10922. ></P
  10923. ><TABLE
  10924. BORDER="1"
  10925. CLASS="CALSTABLE"
  10926. ><COL><COL><COL><THEAD
  10927. ><TR
  10928. ><TH
  10929. >Extension</TH
  10930. ><TH
  10931. >Description</TH
  10932. ><TH
  10933. >Notes</TH
  10934. ></TR
  10935. ></THEAD
  10936. ><TBODY
  10937. ><TR
  10938. ><TD
  10939. >php_bz2.dll</TD
  10940. ><TD
  10941. ><A
  10942. HREF="#ref.bzip2"
  10943. >bzip2</A
  10944. > compression functions</TD
  10945. ><TD
  10946. >None</TD
  10947. ></TR
  10948. ><TR
  10949. ><TD
  10950. >php_calendar.dll</TD
  10951. ><TD
  10952. ><A
  10953. HREF="#ref.calendar"
  10954. >Calendar</A
  10955. > conversion functions</TD
  10956. ><TD
  10957. >Built in since PHP 4.0.3</TD
  10958. ></TR
  10959. ><TR
  10960. ><TD
  10961. >php_cpdf.dll</TD
  10962. ><TD
  10963. ><A
  10964. HREF="#ref.cpdf"
  10965. >ClibPDF</A
  10966. > functions</TD
  10967. ><TD
  10968. >None</TD
  10969. ></TR
  10970. ><TR
  10971. ><TD
  10972. >php_crack.dll</TD
  10973. ><TD
  10974. ><A
  10975. HREF="#ref.crack"
  10976. >Crack</A
  10977. > functions</TD
  10978. ><TD
  10979. >None</TD
  10980. ></TR
  10981. ><TR
  10982. ><TD
  10983. >php_ctype.dll</TD
  10984. ><TD
  10985. ><A
  10986. HREF="#ref.ctype"
  10987. >ctype</A
  10988. > family functions</TD
  10989. ><TD
  10990. >Built in since PHP 4.3.0</TD
  10991. ></TR
  10992. ><TR
  10993. ><TD
  10994. >php_curl.dll</TD
  10995. ><TD
  10996. ><A
  10997. HREF="#ref.curl"
  10998. >CURL</A
  10999. >, Client URL library functions</TD
  11000. ><TD
  11001. >Requires: <TT
  11002. CLASS="filename"
  11003. >libeay32.dll</TT
  11004. >, 
  11005.    <TT
  11006. CLASS="filename"
  11007. >ssleay32.dll</TT
  11008. > (bundled)</TD
  11009. ></TR
  11010. ><TR
  11011. ><TD
  11012. >php_cybercash.dll</TD
  11013. ><TD
  11014. ><A
  11015. HREF="#ref.cybercash"
  11016. >Cybercash</A
  11017. > payment functions</TD
  11018. ><TD
  11019. >PHP <= 4.2.0</TD
  11020. ></TR
  11021. ><TR
  11022. ><TD
  11023. >php_db.dll</TD
  11024. ><TD
  11025. ><A
  11026. HREF="#ref.dbm"
  11027. >DBM</A
  11028. > functions</TD
  11029. ><TD
  11030. >Deprecated. Use DBA instead (<TT
  11031. CLASS="filename"
  11032. >php_dba.dll</TT
  11033. >)</TD
  11034. ></TR
  11035. ><TR
  11036. ><TD
  11037. >php_dba.dll</TD
  11038. ><TD
  11039. ><A
  11040. HREF="#ref.dba"
  11041. >DBA</A
  11042. >: DataBase (dbm-style) 
  11043.    Abstraction layer functions</TD
  11044. ><TD
  11045. >None</TD
  11046. ></TR
  11047. ><TR
  11048. ><TD
  11049. >php_dbase.dll</TD
  11050. ><TD
  11051. ><A
  11052. HREF="#ref.dbase"
  11053. >dBase</A
  11054. > functions</TD
  11055. ><TD
  11056. >None</TD
  11057. ></TR
  11058. ><TR
  11059. ><TD
  11060. >php_dbx.dll</TD
  11061. ><TD
  11062. ><A
  11063. HREF="#ref.dbx"
  11064. >dbx</A
  11065. > functions</TD
  11066. ><TD
  11067. > </TD
  11068. ></TR
  11069. ><TR
  11070. ><TD
  11071. >php_domxml.dll</TD
  11072. ><TD
  11073. ><A
  11074. HREF="#ref.domxml"
  11075. >DOM XML</A
  11076. > functions</TD
  11077. ><TD
  11078. >     PHP <= 4.2.0 requires: <TT
  11079. CLASS="filename"
  11080. >libxml2.dll</TT
  11081. > (bundled)
  11082.     PHP >= 4.3.0 requires: <TT
  11083. CLASS="filename"
  11084. >iconv.dll</TT
  11085. > (bundled)
  11086.    </TD
  11087. ></TR
  11088. ><TR
  11089. ><TD
  11090. >php_dotnet.dll</TD
  11091. ><TD
  11092. ><A
  11093. HREF="#ref.dotnet"
  11094. >.NET</A
  11095. > functions</TD
  11096. ><TD
  11097. >PHP <= 4.1.1</TD
  11098. ></TR
  11099. ><TR
  11100. ><TD
  11101. >php_exif.dll</TD
  11102. ><TD
  11103. ><A
  11104. HREF="#ref.exif"
  11105. >EXIF</A
  11106. > functions</TD
  11107. ><TD
  11108. >     <A
  11109. HREF="#ref.mbstring"
  11110. >php_mbstring.dll</A
  11111. >. And, 
  11112.     <TT
  11113. CLASS="filename"
  11114. >php_exif.dll</TT
  11115. > must be loaded <VAR
  11116. CLASS="literal"
  11117. >after</VAR
  11118. > 
  11119.     <TT
  11120. CLASS="filename"
  11121. >php_mbstring.dll</TT
  11122. > in <TT
  11123. CLASS="filename"
  11124. >php.ini</TT
  11125. >.
  11126.    </TD
  11127. ></TR
  11128. ><TR
  11129. ><TD
  11130. >php_fbsql.dll</TD
  11131. ><TD
  11132. ><A
  11133. HREF="#ref.fbsql"
  11134. >FrontBase</A
  11135. > functions</TD
  11136. ><TD
  11137. >PHP <= 4.2.0</TD
  11138. ></TR
  11139. ><TR
  11140. ><TD
  11141. >php_fdf.dll</TD
  11142. ><TD
  11143. ><A
  11144. HREF="#ref.fdf"
  11145. >FDF</A
  11146. >: Forms Data Format functions.</TD
  11147. ><TD
  11148. >Requires: <TT
  11149. CLASS="filename"
  11150. >fdftk.dll</TT
  11151. > (bundled)</TD
  11152. ></TR
  11153. ><TR
  11154. ><TD
  11155. >php_filepro.dll</TD
  11156. ><TD
  11157. ><A
  11158. HREF="#ref.filepro"
  11159. >filePro</A
  11160. > functions</TD
  11161. ><TD
  11162. >Read-only access</TD
  11163. ></TR
  11164. ><TR
  11165. ><TD
  11166. >php_ftp.dll</TD
  11167. ><TD
  11168. ><A
  11169. HREF="#ref.ftp"
  11170. >FTP</A
  11171. > functions</TD
  11172. ><TD
  11173. >Built-in since PHP 4.0.3</TD
  11174. ></TR
  11175. ><TR
  11176. ><TD
  11177. >php_gd.dll</TD
  11178. ><TD
  11179. ><A
  11180. HREF="#ref.image"
  11181. >GD</A
  11182. > library image functions</TD
  11183. ><TD
  11184. >     Removed in PHP 4.3.2.  Also note that truecolor functions are not
  11185.     available in GD1, instead, use <TT
  11186. CLASS="filename"
  11187. >php_gd2.dll</TT
  11188. >.
  11189.    </TD
  11190. ></TR
  11191. ><TR
  11192. ><TD
  11193. >php_gd2.dll</TD
  11194. ><TD
  11195. ><A
  11196. HREF="#ref.image"
  11197. >GD</A
  11198. > library image functions</TD
  11199. ><TD
  11200. >GD2</TD
  11201. ></TR
  11202. ><TR
  11203. ><TD
  11204. >php_gettext.dll</TD
  11205. ><TD
  11206. ><A
  11207. HREF="#ref.gettext"
  11208. >Gettext</A
  11209. > functions</TD
  11210. ><TD
  11211. >     PHP <= 4.2.0 requires <TT
  11212. CLASS="filename"
  11213. >gnu_gettext.dll</TT
  11214. > (bundled), 
  11215.     PHP >= 4.2.3 requires <TT
  11216. CLASS="filename"
  11217. >libintl-1.dll</TT
  11218. >,
  11219.     <TT
  11220. CLASS="filename"
  11221. >iconv.dll</TT
  11222. > (bundled).
  11223.    </TD
  11224. ></TR
  11225. ><TR
  11226. ><TD
  11227. >php_hyperwave.dll</TD
  11228. ><TD
  11229. ><A
  11230. HREF="#ref.hw"
  11231. >HyperWave</A
  11232. > functions</TD
  11233. ><TD
  11234. >None</TD
  11235. ></TR
  11236. ><TR
  11237. ><TD
  11238. >php_iconv.dll</TD
  11239. ><TD
  11240. ><A
  11241. HREF="#ref.iconv"
  11242. >ICONV</A
  11243. > characterset conversion</TD
  11244. ><TD
  11245. >Requires: <TT
  11246. CLASS="filename"
  11247. >iconv-1.3.dll</TT
  11248. > (bundled), 
  11249.    PHP >=4.2.1 <TT
  11250. CLASS="filename"
  11251. >iconv.dll</TT
  11252. ></TD
  11253. ></TR
  11254. ><TR
  11255. ><TD
  11256. >php_ifx.dll</TD
  11257. ><TD
  11258. ><A
  11259. HREF="#ref.ifx"
  11260. >Informix</A
  11261. > functions</TD
  11262. ><TD
  11263. >Requires: Informix libraries</TD
  11264. ></TR
  11265. ><TR
  11266. ><TD
  11267. >php_iisfunc.dll</TD
  11268. ><TD
  11269. >IIS management functions</TD
  11270. ><TD
  11271. >None</TD
  11272. ></TR
  11273. ><TR
  11274. ><TD
  11275. >php_imap.dll</TD
  11276. ><TD
  11277. ><A
  11278. HREF="#ref.imap"
  11279. >IMAP</A
  11280. > POP3 and NNTP functions</TD
  11281. ><TD
  11282. >None</TD
  11283. ></TR
  11284. ><TR
  11285. ><TD
  11286. >php_ingres.dll</TD
  11287. ><TD
  11288. ><A
  11289. HREF="#ref.ingres"
  11290. >Ingres II</A
  11291. > functions</TD
  11292. ><TD
  11293. >Requires: Ingres II libraries</TD
  11294. ></TR
  11295. ><TR
  11296. ><TD
  11297. >php_interbase.dll</TD
  11298. ><TD
  11299. ><A
  11300. HREF="#ref.ibase"
  11301. >InterBase</A
  11302. > functions</TD
  11303. ><TD
  11304. >Requires: <TT
  11305. CLASS="filename"
  11306. >gds32.dll</TT
  11307. > (bundled)</TD
  11308. ></TR
  11309. ><TR
  11310. ><TD
  11311. >php_java.dll</TD
  11312. ><TD
  11313. ><A
  11314. HREF="#ref.java"
  11315. >Java</A
  11316. > functions</TD
  11317. ><TD
  11318. >PHP <= 4.0.6 requires: <TT
  11319. CLASS="filename"
  11320. >jvm.dll</TT
  11321. > (bundled)</TD
  11322. ></TR
  11323. ><TR
  11324. ><TD
  11325. >php_ldap.dll</TD
  11326. ><TD
  11327. ><A
  11328. HREF="#ref.ldap"
  11329. >LDAP</A
  11330. > functions</TD
  11331. ><TD
  11332. >     PHP <= 4.2.0 requires <TT
  11333. CLASS="filename"
  11334. >libsasl.dll</TT
  11335. > (bundled), 
  11336.     PHP >= 4.3.0 requires <TT
  11337. CLASS="filename"
  11338. >libeay32.dll</TT
  11339. >, 
  11340.     <TT
  11341. CLASS="filename"
  11342. >ssleay32.dll</TT
  11343. > (bundled)
  11344.    </TD
  11345. ></TR
  11346. ><TR
  11347. ><TD
  11348. >php_mbstring.dll</TD
  11349. ><TD
  11350. ><A
  11351. HREF="#ref.mbstring"
  11352. >Multi-Byte String</A
  11353. > functions</TD
  11354. ><TD
  11355. >None</TD
  11356. ></TR
  11357. ><TR
  11358. ><TD
  11359. >php_mcrypt.dll</TD
  11360. ><TD
  11361. ><A
  11362. HREF="#ref.mcrypt"
  11363. >Mcrypt Encryption</A
  11364. > functions</TD
  11365. ><TD
  11366. >Requires: <TT
  11367. CLASS="filename"
  11368. >libmcrypt.dll</TT
  11369. ></TD
  11370. ></TR
  11371. ><TR
  11372. ><TD
  11373. >php_mhash.dll</TD
  11374. ><TD
  11375. ><A
  11376. HREF="#ref.mhash"
  11377. >Mhash</A
  11378. > functions</TD
  11379. ><TD
  11380. >PHP >= 4.3.0 requires: <TT
  11381. CLASS="filename"
  11382. >libmhash.dll</TT
  11383. > (bundled)</TD
  11384. ></TR
  11385. ><TR
  11386. ><TD
  11387. >php_mime_magic.dll</TD
  11388. ><TD
  11389. ><A
  11390. HREF="#ref.mime-magic"
  11391. >Mimetype</A
  11392. > functions</TD
  11393. ><TD
  11394. >Requires: <TT
  11395. CLASS="filename"
  11396. >magic.mime</TT
  11397. > (bundled)</TD
  11398. ></TR
  11399. ><TR
  11400. ><TD
  11401. >php_ming.dll</TD
  11402. ><TD
  11403. ><A
  11404. HREF="#ref.ming"
  11405. >Ming</A
  11406. > functions for Flash</TD
  11407. ><TD
  11408. >None</TD
  11409. ></TR
  11410. ><TR
  11411. ><TD
  11412. >php_msql.dll</TD
  11413. ><TD
  11414. ><A
  11415. HREF="#ref.msql"
  11416. >mSQL</A
  11417. > functions</TD
  11418. ><TD
  11419. >Requires: <TT
  11420. CLASS="filename"
  11421. >msql.dll</TT
  11422. > (bundled)</TD
  11423. ></TR
  11424. ><TR
  11425. ><TD
  11426. >php_mssql.dll</TD
  11427. ><TD
  11428. ><A
  11429. HREF="#ref.mssql"
  11430. >MSSQL</A
  11431. > functions</TD
  11432. ><TD
  11433. >Requires: <TT
  11434. CLASS="filename"
  11435. >ntwdblib.dll</TT
  11436. > (bundled)</TD
  11437. ></TR
  11438. ><TR
  11439. ><TD
  11440. >php_mysql.dll</TD
  11441. ><TD
  11442. ><A
  11443. HREF="#ref.mysql"
  11444. >MySQL</A
  11445. > functions</TD
  11446. ><TD
  11447. >PHP >= 5.0.0, requires <TT
  11448. CLASS="filename"
  11449. >libmysql.dll</TT
  11450. >
  11451.     (bundled)</TD
  11452. ></TR
  11453. ><TR
  11454. ><TD
  11455. >php_mysqli.dll</TD
  11456. ><TD
  11457. ><A
  11458. HREF="#ref.mysqli"
  11459. >MySQLi</A
  11460. > functions</TD
  11461. ><TD
  11462. >PHP >= 5.0.0, requires <TT
  11463. CLASS="filename"
  11464. >libmysql.dll</TT
  11465. >
  11466.     (<TT
  11467. CLASS="filename"
  11468. >libmysqli.dll</TT
  11469. > in PHP <= 5.0.2) (bundled)</TD
  11470. ></TR
  11471. ><TR
  11472. ><TD
  11473. >php_oci8.dll</TD
  11474. ><TD
  11475. ><A
  11476. HREF="#ref.oci8"
  11477. >Oracle 8</A
  11478. > functions</TD
  11479. ><TD
  11480. >Requires: Oracle 8.1+ client libraries</TD
  11481. ></TR
  11482. ><TR
  11483. ><TD
  11484. >php_openssl.dll</TD
  11485. ><TD
  11486. ><A
  11487. HREF="#ref.openssl"
  11488. >OpenSSL</A
  11489. > functions</TD
  11490. ><TD
  11491. >Requires: <TT
  11492. CLASS="filename"
  11493. >libeay32.dll</TT
  11494. > (bundled)</TD
  11495. ></TR
  11496. ><TR
  11497. ><TD
  11498. >php_oracle.dll</TD
  11499. ><TD
  11500. ><A
  11501. HREF="#ref.oracle"
  11502. >Oracle</A
  11503. > functions</TD
  11504. ><TD
  11505. >Requires: Oracle 7 client libraries</TD
  11506. ></TR
  11507. ><TR
  11508. ><TD
  11509. >php_overload.dll</TD
  11510. ><TD
  11511. ><A
  11512. HREF="#ref.overload"
  11513. >Object overloading</A
  11514. > functions</TD
  11515. ><TD
  11516. >Built in since PHP 4.3.0</TD
  11517. ></TR
  11518. ><TR
  11519. ><TD
  11520. >php_pdf.dll</TD
  11521. ><TD
  11522. ><A
  11523. HREF="#ref.pdf"
  11524. >PDF</A
  11525. > functions</TD
  11526. ><TD
  11527. >None</TD
  11528. ></TR
  11529. ><TR
  11530. ><TD
  11531. >php_pgsql.dll</TD
  11532. ><TD
  11533. ><A
  11534. HREF="#ref.pgsql"
  11535. >PostgreSQL</A
  11536. > functions</TD
  11537. ><TD
  11538. >None</TD
  11539. ></TR
  11540. ><TR
  11541. ><TD
  11542. >php_printer.dll</TD
  11543. ><TD
  11544. ><A
  11545. HREF="#ref.printer"
  11546. >Printer</A
  11547. > functions</TD
  11548. ><TD
  11549. >None</TD
  11550. ></TR
  11551. ><TR
  11552. ><TD
  11553. >php_shmop.dll</TD
  11554. ><TD
  11555. ><A
  11556. HREF="#ref.shmop"
  11557. >Shared Memory</A
  11558. > functions</TD
  11559. ><TD
  11560. >None</TD
  11561. ></TR
  11562. ><TR
  11563. ><TD
  11564. >php_snmp.dll</TD
  11565. ><TD
  11566. ><A
  11567. HREF="#ref.snmp"
  11568. >SNMP</A
  11569. > get and walk functions</TD
  11570. ><TD
  11571. >NT only!</TD
  11572. ></TR
  11573. ><TR
  11574. ><TD
  11575. >php_soap.dll</TD
  11576. ><TD
  11577. ><A
  11578. HREF="#ref.soap"
  11579. >SOAP</A
  11580. > functions</TD
  11581. ><TD
  11582. >PHP >= 5.0.0</TD
  11583. ></TR
  11584. ><TR
  11585. ><TD
  11586. >php_sockets.dll</TD
  11587. ><TD
  11588. ><A
  11589. HREF="#ref.sockets"
  11590. >Socket</A
  11591. > functions</TD
  11592. ><TD
  11593. >None</TD
  11594. ></TR
  11595. ><TR
  11596. ><TD
  11597. >php_sybase_ct.dll</TD
  11598. ><TD
  11599. ><A
  11600. HREF="#ref.sybase"
  11601. >Sybase</A
  11602. > functions</TD
  11603. ><TD
  11604. >Requires: Sybase client libraries</TD
  11605. ></TR
  11606. ><TR
  11607. ><TD
  11608. >php_tidy.dll</TD
  11609. ><TD
  11610. ><A
  11611. HREF="#ref.tidy"
  11612. >Tidy</A
  11613. > functions</TD
  11614. ><TD
  11615. >PHP >= 5.0.0</TD
  11616. ></TR
  11617. ><TR
  11618. ><TD
  11619. >php_tokenizer.dll</TD
  11620. ><TD
  11621. ><A
  11622. HREF="#ref.tokenizer"
  11623. >Tokenizer</A
  11624. > functions</TD
  11625. ><TD
  11626. >Built in since PHP 4.3.0</TD
  11627. ></TR
  11628. ><TR
  11629. ><TD
  11630. >php_w32api.dll</TD
  11631. ><TD
  11632. ><A
  11633. HREF="#ref.w32api"
  11634. >W32api</A
  11635. > functions</TD
  11636. ><TD
  11637. >None</TD
  11638. ></TR
  11639. ><TR
  11640. ><TD
  11641. >php_xmlrpc.dll</TD
  11642. ><TD
  11643. ><A
  11644. HREF="#ref.xmlrpc"
  11645. >XML-RPC</A
  11646. > functions</TD
  11647. ><TD
  11648. >PHP >= 4.2.1 requires: <TT
  11649. CLASS="filename"
  11650. >iconv.dll</TT
  11651. > (bundled)</TD
  11652. ></TR
  11653. ><TR
  11654. ><TD
  11655. >php_xslt.dll</TD
  11656. ><TD
  11657. ><A
  11658. HREF="#ref.xslt"
  11659. >XSLT</A
  11660. > functions</TD
  11661. ><TD
  11662. >     PHP <= 4.2.0 requires <TT
  11663. CLASS="filename"
  11664. >sablot.dll</TT
  11665. >,
  11666.     <TT
  11667. CLASS="filename"
  11668. >expat.dll</TT
  11669. > (bundled). PHP >= 4.2.1 requires
  11670.     <TT
  11671. CLASS="filename"
  11672. >sablot.dll</TT
  11673. >, <TT
  11674. CLASS="filename"
  11675. >expat.dll</TT
  11676. >,
  11677.     <TT
  11678. CLASS="filename"
  11679. >iconv.dll</TT
  11680. > (bundled).
  11681.    </TD
  11682. ></TR
  11683. ><TR
  11684. ><TD
  11685. >php_yaz.dll</TD
  11686. ><TD
  11687. ><A
  11688. HREF="#ref.yaz"
  11689. >YAZ</A
  11690. > functions</TD
  11691. ><TD
  11692. >Requires: <TT
  11693. CLASS="filename"
  11694. >yaz.dll</TT
  11695. > (bundled)</TD
  11696. ></TR
  11697. ><TR
  11698. ><TD
  11699. >php_zip.dll</TD
  11700. ><TD
  11701. ><A
  11702. HREF="#ref.zip"
  11703. >Zip File</A
  11704. > functions</TD
  11705. ><TD
  11706. >Read only access</TD
  11707. ></TR
  11708. ><TR
  11709. ><TD
  11710. >php_zlib.dll</TD
  11711. ><TD
  11712. ><A
  11713. HREF="#ref.zlib"
  11714. >ZLib</A
  11715. > compression functions</TD
  11716. ><TD
  11717. >Built in since PHP 4.3.0</TD
  11718. ></TR
  11719. ></TBODY
  11720. ></TABLE
  11721. ></DIV
  11722. >
  11723.     </P
  11724. ></DIV
  11725. ></DIV
  11726. ><DIV
  11727. CLASS="chapter"
  11728. ><HR><H1
  11729. ><A
  11730. NAME="install.pecl"
  11731. >Chapter 7. Installation of PECL extensions</A
  11732. ></H1
  11733. ><DIV
  11734. CLASS="sect1"
  11735. ><H2
  11736. CLASS="sect1"
  11737. ><A
  11738. NAME="install.pecl.intro"
  11739. >Introduction to PECL Installations</A
  11740. ></H2
  11741. ><P
  11742. >    PHP extensions may be installed in a variety of ways. 
  11743.    <A
  11744. HREF="http://pecl.php.net"
  11745. TARGET="_top"
  11746. >PECL</A
  11747. > is a repository of PHP extensions 
  11748.    living within the <A
  11749. HREF="http://pear.php.net/"
  11750. TARGET="_top"
  11751. >PEAR</A
  11752. > structure, and 
  11753.    the following demonstrates how to install these extensions.
  11754.   </P
  11755. ><P
  11756. >    These instructions assume <VAR
  11757. CLASS="literal"
  11758. >/your/phpsrcdir/</VAR
  11759. > is the path
  11760.    to the PHP source, and <VAR
  11761. CLASS="literal"
  11762. >extname</VAR
  11763. > is the name of the
  11764.    PECL extension.  Adjust accordingly.  These instructions also assume a 
  11765.    familiarity with the <A
  11766. HREF="http://pear.php.net/manual/en/installation.cli.php"
  11767. TARGET="_top"
  11768. >pear command</A
  11769. >.
  11770.   </P
  11771. ><P
  11772. >    Shared extensions may be installed by including them inside of <TT
  11773. CLASS="filename"
  11774. >php.ini</TT
  11775. >
  11776.    using the <A
  11777. HREF="#ini.extension"
  11778. >extension</A
  11779. > PHP directive. See
  11780.    also the <A
  11781. HREF="#ini.extension-dir"
  11782. >extensions_dir</A
  11783. >
  11784.    directive, and <A
  11785. HREF="#function.dl"
  11786. ><B
  11787. CLASS="function"
  11788. >dl()</B
  11789. ></A
  11790. >.  The installation methods described
  11791.    below do not automatically configure PHP to include these extensions, this 
  11792.    step must be done manually.
  11793.   </P
  11794. ><P
  11795. >    When building PHP modules, it's important to have the appropriate versions 
  11796.    of the required tools (autoconf, automake, libtool, etc.) See the 
  11797.    <A
  11798. HREF="http://www.php.net/anoncvs.php"
  11799. TARGET="_top"
  11800. >Anonymous CVS Instructions</A
  11801. > for 
  11802.    details on the required tools, and required versions.
  11803.   </P
  11804. ></DIV
  11805. ><DIV
  11806. CLASS="sect1"
  11807. ><HR><H2
  11808. CLASS="sect1"
  11809. ><A
  11810. NAME="install.pecl.downloads"
  11811. >Downloading PECL extensions</A
  11812. ></H2
  11813. ><P
  11814. >    There are several options for downloading PECL extensions, such as:
  11815.   </P
  11816. ><P
  11817. ></P
  11818. ><UL
  11819. ><LI
  11820. ><P
  11821. >      <A
  11822. HREF="http://pecl.php.net"
  11823. TARGET="_top"
  11824. >http://pecl.php.net</A
  11825. >
  11826.     </P
  11827. ><P
  11828. >      Listed here is information like the ChangeLog, release information, 
  11829.      requirements, revisions, etc.  Although not every PECL extension has a
  11830.      webpage, most do.
  11831.     </P
  11832. ></LI
  11833. ><LI
  11834. ><P
  11835. >      <VAR
  11836. CLASS="literal"
  11837. >pear download extname</VAR
  11838. >
  11839.     </P
  11840. ><P
  11841. >      The <A
  11842. HREF="http://pear.php.net/manual/en/installation.cli.php"
  11843. TARGET="_top"
  11844. >pear command</A
  11845. > may also be used 
  11846.      to download source files.  Specific revisions may also be specified.
  11847.     </P
  11848. ></LI
  11849. ><LI
  11850. ><P
  11851. >      <ACRONYM
  11852. CLASS="acronym"
  11853. >CVS</ACRONYM
  11854. >
  11855.     </P
  11856. ><P
  11857. >      All PECL files reside in <ACRONYM
  11858. CLASS="acronym"
  11859. >CVS</ACRONYM
  11860. >.  A web-based view may
  11861.      be seen at <A
  11862. HREF="http://cvs.php.net/pecl/"
  11863. TARGET="_top"
  11864. >http://cvs.php.net/pecl/</A
  11865. >.  
  11866.      To download straight from <ACRONYM
  11867. CLASS="acronym"
  11868. >CVS</ACRONYM
  11869. >, consider the following 
  11870.      where <SPAN
  11871. CLASS="emphasis"
  11872. ><I
  11873. CLASS="emphasis"
  11874. >phpfi</I
  11875. ></SPAN
  11876. > is the password for user 
  11877.      <SPAN
  11878. CLASS="emphasis"
  11879. ><I
  11880. CLASS="emphasis"
  11881. >cvsread</I
  11882. ></SPAN
  11883. >:
  11884.     </P
  11885. ><P
  11886. >      <TABLE
  11887. BORDER="0"
  11888. BGCOLOR="#E0E0E0"
  11889. CELLPADDING="5"
  11890. ><TR
  11891. ><TD
  11892. ><PRE
  11893. CLASS="screen"
  11894. >$ cvs -d:pserver:cvsread@cvs.php.net:/repository login 
  11895. $ cvs -d:pserver:cvsread@cvs.php.net:/repository co pecl/extname</PRE
  11896. ></TD
  11897. ></TR
  11898. ></TABLE
  11899. >
  11900.     </P
  11901. ></LI
  11902. ><LI
  11903. ><P
  11904. >      Windows downloads
  11905.     </P
  11906. ><P
  11907. >      Windows users may find compiled PECL binaries by downloading the
  11908.      <SPAN
  11909. CLASS="emphasis"
  11910. ><I
  11911. CLASS="emphasis"
  11912. >Collection of PECL modules</I
  11913. ></SPAN
  11914. > from the 
  11915.      <A
  11916. HREF="http://www.php.net/downloads.php"
  11917. TARGET="_top"
  11918. >PHP Downloads</A
  11919. > page, and by
  11920.      retrieving a <A
  11921. HREF="http://snaps.php.net/"
  11922. TARGET="_top"
  11923. >PECL Snapshot</A
  11924. >.  To
  11925.      compile PHP under Windows, read the 
  11926.      <A
  11927. HREF="http://cvs.php.net/co.php/php-src/README.WIN32-BUILD-SYSTEM"
  11928. TARGET="_top"
  11929. >Win32 Build README</A
  11930. >.
  11931.     </P
  11932. ></LI
  11933. ></UL
  11934. ></DIV
  11935. ><DIV
  11936. CLASS="sect1"
  11937. ><HR><H2
  11938. CLASS="sect1"
  11939. ><A
  11940. NAME="install.pecl.windows"
  11941. >PECL for Windows users</A
  11942. ></H2
  11943. ><P
  11944. >    Like with any other PHP extension <ACRONYM
  11945. CLASS="acronym"
  11946. >DLL</ACRONYM
  11947. >, to install move 
  11948.    the PECL extension DLLs into the <A
  11949. HREF="#ini.extension-dir"
  11950. >    extension_dir</A
  11951. > folder and include them within <TT
  11952. CLASS="filename"
  11953. >php.ini</TT
  11954. >.  For 
  11955.    example:
  11956.   </P
  11957. ><P
  11958. >    <TABLE
  11959. BORDER="0"
  11960. BGCOLOR="#E0E0E0"
  11961. CELLPADDING="5"
  11962. ><TR
  11963. ><TD
  11964. ><PRE
  11965. CLASS="screen"
  11966. >extension=php_extname.dll</PRE
  11967. ></TD
  11968. ></TR
  11969. ></TABLE
  11970. >
  11971.   </P
  11972. ><P
  11973. >    After doing this, restart the web server.
  11974.   </P
  11975. ></DIV
  11976. ><DIV
  11977. CLASS="sect1"
  11978. ><HR><H2
  11979. CLASS="sect1"
  11980. ><A
  11981. NAME="install.pecl.pear"
  11982. >Compiling shared PECL extensions with PEAR</A
  11983. ></H2
  11984. ><P
  11985. >    PEAR makes it easy to create shared PHP extensions. Using the 
  11986.    <A
  11987. HREF="http://pear.php.net/manual/en/installation.cli.php"
  11988. TARGET="_top"
  11989. >pear command</A
  11990. >, do the following:
  11991.   </P
  11992. ><P
  11993. >    <TABLE
  11994. BORDER="0"
  11995. BGCOLOR="#E0E0E0"
  11996. CELLPADDING="5"
  11997. ><TR
  11998. ><TD
  11999. ><PRE
  12000. CLASS="screen"
  12001. >$ pear install extname</PRE
  12002. ></TD
  12003. ></TR
  12004. ></TABLE
  12005. >
  12006.   </P
  12007. ><P
  12008. >    That will download the source for <SPAN
  12009. CLASS="emphasis"
  12010. ><I
  12011. CLASS="emphasis"
  12012. >extname</I
  12013. ></SPAN
  12014. >, and 
  12015.    compile it on the system. This results in an 
  12016.    <TT
  12017. CLASS="filename"
  12018. >extname.so</TT
  12019. > file that may then be included in <TT
  12020. CLASS="filename"
  12021. >php.ini</TT
  12022. >
  12023.   </P
  12024. ><P
  12025. >    In case the systems <SPAN
  12026. CLASS="emphasis"
  12027. ><I
  12028. CLASS="emphasis"
  12029. >preferred_state</I
  12030. ></SPAN
  12031. > is set higher than
  12032.    an available <SPAN
  12033. CLASS="emphasis"
  12034. ><I
  12035. CLASS="emphasis"
  12036. >extname</I
  12037. ></SPAN
  12038. > version, like it's set to stable 
  12039.    and the extension is still in beta, either alter the 
  12040.    <SPAN
  12041. CLASS="emphasis"
  12042. ><I
  12043. CLASS="emphasis"
  12044. >preferred_state</I
  12045. ></SPAN
  12046. > via <VAR
  12047. CLASS="literal"
  12048. >pear config-set</VAR
  12049. > 
  12050.    or specify a specific version of the PECL extension. For example:
  12051.   </P
  12052. ><P
  12053. >    <TABLE
  12054. BORDER="0"
  12055. BGCOLOR="#E0E0E0"
  12056. CELLPADDING="5"
  12057. ><TR
  12058. ><TD
  12059. ><PRE
  12060. CLASS="screen"
  12061. >$ pear install extname-0.1.1</PRE
  12062. ></TD
  12063. ></TR
  12064. ></TABLE
  12065. >
  12066.   </P
  12067. ><P
  12068. >    Regardless, pear will copy this <TT
  12069. CLASS="filename"
  12070. >extname.so</TT
  12071. > into the 
  12072.    <A
  12073. HREF="#ini.extension-dir"
  12074. >extensions directory</A
  12075. >. Adjust  
  12076.    <TT
  12077. CLASS="filename"
  12078. >php.ini</TT
  12079. > accordingly.
  12080.   </P
  12081. ></DIV
  12082. ><DIV
  12083. CLASS="sect1"
  12084. ><HR><H2
  12085. CLASS="sect1"
  12086. ><A
  12087. NAME="install.pecl.phpize"
  12088. >Compiling shared PECL extensions with phpize</A
  12089. ></H2
  12090. ><P
  12091. >    If using pear is not an option, like for building shared PECL extensions
  12092.    from <ACRONYM
  12093. CLASS="acronym"
  12094. >CVS</ACRONYM
  12095. >, or for unreleased PECL packages, then creating 
  12096.    a shared extension may also be done by manually using the 
  12097.    <VAR
  12098. CLASS="literal"
  12099. >phpize</VAR
  12100. > command. The pear command essentially does this 
  12101.    but it may also be done manually. Assuming the source file is named 
  12102.    <TT
  12103. CLASS="filename"
  12104. >extname.tgz</TT
  12105. >, and that it was downloaded into the 
  12106.    current directory, consider the following:
  12107.   </P
  12108. ><P
  12109. >    <TABLE
  12110. BORDER="0"
  12111. BGCOLOR="#E0E0E0"
  12112. CELLPADDING="5"
  12113. ><TR
  12114. ><TD
  12115. ><PRE
  12116. CLASS="screen"
  12117. >$ pear download extname
  12118. $ gzip -d < extname.tgz | tar -xvf -
  12119. $ cd extname
  12120. $ phpize
  12121. $ ./configure && make</PRE
  12122. ></TD
  12123. ></TR
  12124. ></TABLE
  12125. >
  12126.   </P
  12127. ><P
  12128. >    Upon success, this will create <TT
  12129. CLASS="filename"
  12130. >extname.so</TT
  12131. > and put it 
  12132.    into the <TT
  12133. CLASS="filename"
  12134. >modules/</TT
  12135. > and/or <TT
  12136. CLASS="filename"
  12137. >.libs/</TT
  12138. > 
  12139.    directory within the <TT
  12140. CLASS="filename"
  12141. >extname/</TT
  12142. > source. Move this 
  12143.    shared extension (<TT
  12144. CLASS="filename"
  12145. >extname.so</TT
  12146. >) into the PHP 
  12147.    <A
  12148. HREF="#ini.extension-dir"
  12149. >extensions directory</A
  12150. >, and adjust
  12151.    <TT
  12152. CLASS="filename"
  12153. >php.ini</TT
  12154. > accordingly.
  12155.   </P
  12156. ></DIV
  12157. ><DIV
  12158. CLASS="sect1"
  12159. ><HR><H2
  12160. CLASS="sect1"
  12161. ><A
  12162. NAME="install.pecl.static"
  12163. >Compiling PECL extensions statically into PHP</A
  12164. ></H2
  12165. ><P
  12166. >    To statically include the extension within the PHP build, put the 
  12167.    extensions source into the <TT
  12168. CLASS="filename"
  12169. >ext/</TT
  12170. > directory found in 
  12171.    the PHP source. For example:
  12172.   </P
  12173. ><P
  12174. >    <TABLE
  12175. BORDER="0"
  12176. BGCOLOR="#E0E0E0"
  12177. CELLPADDING="5"
  12178. ><TR
  12179. ><TD
  12180. ><PRE
  12181. CLASS="screen"
  12182. >$ cd /your/phpsrcdir/ext
  12183. $ pear download extname
  12184. $ gzip -d < extname.tgz | tar -xvf -
  12185. $ mv extname-x.x.x extname
  12186. $ rm package.xml</PRE
  12187. ></TD
  12188. ></TR
  12189. ></TABLE
  12190. >
  12191.   </P
  12192. ><P
  12193. >    This will result in the following directory:
  12194.   </P
  12195. ><P
  12196. >    <TABLE
  12197. BORDER="0"
  12198. BGCOLOR="#E0E0E0"
  12199. CELLPADDING="5"
  12200. ><TR
  12201. ><TD
  12202. ><PRE
  12203. CLASS="screen"
  12204. >/your/phpsrcdir/ext/extname</PRE
  12205. ></TD
  12206. ></TR
  12207. ></TABLE
  12208. >
  12209.   </P
  12210. ><P
  12211. >    From here, build PHP as normal:
  12212.   </P
  12213. ><P
  12214. >    <TABLE
  12215. BORDER="0"
  12216. BGCOLOR="#E0E0E0"
  12217. CELLPADDING="5"
  12218. ><TR
  12219. ><TD
  12220. ><PRE
  12221. CLASS="screen"
  12222. >$ cd /your/phpsrcdir 
  12223. $ ./buildconf
  12224. $ ./configure --help
  12225. $ ./configure --with-extname --enable-someotherext --with-foobar
  12226. $ make
  12227. $ make install</PRE
  12228. ></TD
  12229. ></TR
  12230. ></TABLE
  12231. >
  12232.   </P
  12233. ><P
  12234. >    Whether <VAR
  12235. CLASS="literal"
  12236. >--enable-extname</VAR
  12237. > or <VAR
  12238. CLASS="literal"
  12239. >--with-extname
  12240.    </VAR
  12241. > is used depends on the extension. Typically an extension that 
  12242.    does not require external libraries uses <VAR
  12243. CLASS="literal"
  12244. >--enable</VAR
  12245. >. To be
  12246.    sure, run the following after buildconf:
  12247.   </P
  12248. ><P
  12249. >    <TABLE
  12250. BORDER="0"
  12251. BGCOLOR="#E0E0E0"
  12252. CELLPADDING="5"
  12253. ><TR
  12254. ><TD
  12255. ><PRE
  12256. CLASS="screen"
  12257. >$ ./configure --help | grep extname</PRE
  12258. ></TD
  12259. ></TR
  12260. ></TABLE
  12261. >
  12262.   </P
  12263. ></DIV
  12264. ></DIV
  12265. ><DIV
  12266. CLASS="chapter"
  12267. ><HR><H1
  12268. ><A
  12269. NAME="install.problems"
  12270. >Chapter 8. Problems?</A
  12271. ></H1
  12272. ><DIV
  12273. CLASS="sect1"
  12274. ><H2
  12275. CLASS="sect1"
  12276. ><A
  12277. NAME="install.problems.faq"
  12278. >Read the FAQ</A
  12279. ></H2
  12280. ><P
  12281. >      Some problems are more common than others. The most
  12282.      common ones are listed in the <A
  12283. HREF="#faq"
  12284. >PHP
  12285.      FAQ</A
  12286. >, part of this manual.
  12287.     </P
  12288. ></DIV
  12289. ><DIV
  12290. CLASS="sect1"
  12291. ><HR><H2
  12292. CLASS="sect1"
  12293. ><A
  12294. NAME="install.problems.support"
  12295. >Other problems</A
  12296. ></H2
  12297. ><P
  12298. >      If you are still stuck, someone on the PHP installation mailing list may be
  12299.      able to help you. You should check out the archive first, in case
  12300.      someone already answered someone else who had the same problem as
  12301.      you. The archives are available from the support page on <A
  12302. HREF="http://www.php.net/support.php"
  12303. TARGET="_top"
  12304. >http://www.php.net/support.php</A
  12305. >. To subscribe to the PHP installation
  12306.      mailing list, send an empty mail to <A
  12307. HREF="mailto:php-install-subscribe@lists.php.net"
  12308. TARGET="_top"
  12309. >php-install-subscribe@lists.php.net</A
  12310. >.
  12311.      The mailing list address is <A
  12312. HREF="mailto:php-install@lists.php.net"
  12313. TARGET="_top"
  12314. >php-install@lists.php.net</A
  12315. >.
  12316.     </P
  12317. ><P
  12318. >      If you want to get help on the mailing list, please try to be
  12319.      precise and give the necessary details about your environment
  12320.      (which operating system, what PHP version, what web server, if
  12321.      you are running PHP as CGI or a server module, <A
  12322. HREF="#ini.safe-mode"
  12323. >safe mode</A
  12324. >, etc...), and
  12325.      preferably enough code to make others able to reproduce and test
  12326.      your problem.
  12327.     </P
  12328. ></DIV
  12329. ><DIV
  12330. CLASS="sect1"
  12331. ><HR><H2
  12332. CLASS="sect1"
  12333. ><A
  12334. NAME="install.problems.bugs"
  12335. >Bug reports</A
  12336. ></H2
  12337. ><P
  12338. >      If you think you have found a bug in PHP, please report it.  The
  12339.      PHP developers probably don't know about it, and unless you
  12340.      report it, chances are it won't be fixed. You can report bugs
  12341.      using the bug-tracking system at <A
  12342. HREF="http://bugs.php.net/"
  12343. TARGET="_top"
  12344. >http://bugs.php.net/</A
  12345. >. Please do not
  12346.      send bug reports in mailing list or personal letters. The
  12347.      bug system is also suitable to submit feature requests.
  12348.     </P
  12349. ><P
  12350. >      Read the <A
  12351. HREF="http://bugs.php.net/how-to-report.php"
  12352. TARGET="_top"
  12353. >How to report a bug</A
  12354. > 
  12355.      document before submitting any bug reports!
  12356.     </P
  12357. ></DIV
  12358. ></DIV
  12359. ><DIV
  12360. CLASS="chapter"
  12361. ><HR><H1
  12362. ><A
  12363. NAME="configuration"
  12364. >Chapter 9. Runtime Configuration</A
  12365. ></H1
  12366. ><DIV
  12367. CLASS="sect1"
  12368. ><H2
  12369. CLASS="sect1"
  12370. ><A
  12371. NAME="configuration.file"
  12372. >The configuration file</A
  12373. ></H2
  12374. ><P
  12375. >     The configuration file (called <TT
  12376. CLASS="filename"
  12377. >php3.ini</TT
  12378. > in
  12379.     PHP 3, and simply <TT
  12380. CLASS="filename"
  12381. >php.ini</TT
  12382. > as of PHP 4)
  12383.     is read when PHP starts up. For the server module versions of PHP,
  12384.     this happens only once when the web server is started. For the
  12385.     <ACRONYM
  12386. CLASS="acronym"
  12387. >CGI</ACRONYM
  12388. > and <ACRONYM
  12389. CLASS="acronym"
  12390. >CLI</ACRONYM
  12391. > version, it happens on
  12392.     every invocation.
  12393.    </P
  12394. ><P
  12395. >     The default location of <TT
  12396. CLASS="filename"
  12397. >php.ini</TT
  12398. > is a compile time option (see the <A
  12399. HREF="#faq.installation.phpini"
  12400. >FAQ</A
  12401. > entry), but can be changed
  12402.     for the <ACRONYM
  12403. CLASS="acronym"
  12404. >CGI</ACRONYM
  12405. > and <ACRONYM
  12406. CLASS="acronym"
  12407. >CLI</ACRONYM
  12408. > version with the
  12409.     <VAR
  12410. CLASS="literal"
  12411. >-c</VAR
  12412. > command line switch, see the chapter about using
  12413.     PHP from the <A
  12414. HREF="#features.commandline"
  12415. >command line</A
  12416. >. You can also use the
  12417.     environment variable <VAR
  12418. CLASS="varname"
  12419. >PHPRC</VAR
  12420. > for an additional path to
  12421.     search for a <TT
  12422. CLASS="filename"
  12423. >php.ini</TT
  12424. > file.
  12425.    </P
  12426. ><P
  12427. >     If <TT
  12428. CLASS="filename"
  12429. >php-SAPI.ini</TT
  12430. > exists (where SAPI is used SAPI, so the
  12431.     filename is e.g. <TT
  12432. CLASS="filename"
  12433. >php-cli.ini</TT
  12434. > or
  12435.     <TT
  12436. CLASS="filename"
  12437. >php-apache.ini</TT
  12438. >), it's used instead of <TT
  12439. CLASS="filename"
  12440. >php.ini</TT
  12441. >.
  12442.    </P
  12443. ><DIV
  12444. CLASS="note"
  12445. ><BLOCKQUOTE
  12446. CLASS="note"
  12447. ><P
  12448. ><B
  12449. >Note: </B
  12450. >
  12451.      The Apache web server changes the directory to root at startup causing
  12452.      PHP to attempt to read <TT
  12453. CLASS="filename"
  12454. >php.ini</TT
  12455. > from the root filesystem if it exists.
  12456.     </P
  12457. ></BLOCKQUOTE
  12458. ></DIV
  12459. ><P
  12460. >     The <TT
  12461. CLASS="filename"
  12462. >php.ini</TT
  12463. > directives handled by extensions are documented respectively
  12464.     on the pages of the extensions themselves. The <A
  12465. HREF="#ini"
  12466. >list of
  12467.     the core directives</A
  12468. > is available in the appendix. Probably not all
  12469.     the PHP directives are documented in the manual though. For a completel list
  12470.     of directives available in your PHP version, please read your well commented
  12471.     <TT
  12472. CLASS="filename"
  12473. >php.ini</TT
  12474. > file. Alternatively, you may find the
  12475.     <A
  12476. HREF="http://cvs.php.net/co.php/php-src/php.ini-dist"
  12477. TARGET="_top"
  12478. >the latest <TT
  12479. CLASS="filename"
  12480. >php.ini</TT
  12481. ></A
  12482. > from CVS
  12483.     helpful too.
  12484.    </P
  12485. ><P
  12486. >     <TABLE
  12487. WIDTH="100%"
  12488. BORDER="0"
  12489. CELLPADDING="0"
  12490. CELLSPACING="0"
  12491. CLASS="EXAMPLE"
  12492. ><TR
  12493. ><TD
  12494. ><DIV
  12495. CLASS="example"
  12496. ><A
  12497. NAME="AEN2389"
  12498. ></A
  12499. ><P
  12500. ><B
  12501. >Example 9-1. <TT
  12502. CLASS="filename"
  12503. >php.ini</TT
  12504. > example</B
  12505. ></P
  12506. ><TABLE
  12507. BORDER="0"
  12508. BGCOLOR="#E0E0E0"
  12509. CELLPADDING="5"
  12510. ><TR
  12511. ><TD
  12512. ><PRE
  12513. CLASS="ini"
  12514. >; any text on a line after an unquoted semicolon (;) is ignored
  12515. [php] ; section markers (text within square brackets) are also ignored
  12516. ; Boolean values can be set to either:
  12517. ;    true, on, yes
  12518. ; or false, off, no, none
  12519. register_globals = off
  12520. track_errors = yes
  12521.  
  12522. ; you can enclose strings in double-quotes
  12523. include_path = ".:/usr/local/lib/php"
  12524.  
  12525. ; backslashes are treated the same as any other character
  12526. include_path = ".;c:\php\lib"</PRE
  12527. ></TD
  12528. ></TR
  12529. ></TABLE
  12530. ></DIV
  12531. ></TD
  12532. ></TR
  12533. ></TABLE
  12534. >
  12535.    </P
  12536. ></DIV
  12537. ><DIV
  12538. CLASS="sect1"
  12539. ><HR><H2
  12540. CLASS="sect1"
  12541. ><A
  12542. NAME="configuration.changes"
  12543. >How to change configuration settings</A
  12544. ></H2
  12545. ><DIV
  12546. CLASS="sect2"
  12547. ><H3
  12548. CLASS="sect2"
  12549. ><A
  12550. NAME="configuration.changes.apache"
  12551. >Running PHP as an Apache module</A
  12552. ></H3
  12553. ><P
  12554. >      When using PHP as an Apache module, you can also change the
  12555.      configuration settings using directives in Apache configuration
  12556.      files (e.g. <TT
  12557. CLASS="filename"
  12558. >httpd.conf</TT
  12559. >) and <TT
  12560. CLASS="filename"
  12561. >.htaccess</TT
  12562. > files. You will need
  12563.      "AllowOverride Options" or "AllowOverride All" privileges to do so.
  12564.     </P
  12565. ><P
  12566. >      With PHP 4 and PHP 5, there are several Apache directives that allow you
  12567.      to change the PHP configuration from within the Apache configuration
  12568.      files.  For a listing of which directives are 
  12569.      <TT
  12570. CLASS="constant"
  12571. ><B
  12572. >PHP_INI_ALL</B
  12573. ></TT
  12574. >, <TT
  12575. CLASS="constant"
  12576. ><B
  12577. >PHP_INI_PERDIR</B
  12578. ></TT
  12579. >, 
  12580.      or <TT
  12581. CLASS="constant"
  12582. ><B
  12583. >PHP_INI_SYSTEM</B
  12584. ></TT
  12585. >, have a look at the table
  12586.      found within the <A
  12587. HREF="#function.ini-set"
  12588. ><B
  12589. CLASS="function"
  12590. >ini_set()</B
  12591. ></A
  12592. > documentation.
  12593.     </P
  12594. ><DIV
  12595. CLASS="note"
  12596. ><BLOCKQUOTE
  12597. CLASS="note"
  12598. ><P
  12599. ><B
  12600. >Note: </B
  12601. >
  12602.       With PHP 3, there are Apache directives that correspond to each
  12603.       configuration setting in the <TT
  12604. CLASS="filename"
  12605. >php3.ini</TT
  12606. > name,
  12607.       except the name is prefixed by "php3_".
  12608.      </P
  12609. ></BLOCKQUOTE
  12610. ></DIV
  12611. ><P
  12612. >      <P
  12613. ></P
  12614. ><DIV
  12615. CLASS="variablelist"
  12616. ><DL
  12617. ><DT
  12618. ><SPAN
  12619. CLASS="systemitem"
  12620. >php_value</SPAN
  12621. >
  12622.         <VAR
  12623. CLASS="parameter"
  12624. >name</VAR
  12625. >
  12626.         <VAR
  12627. CLASS="parameter"
  12628. >value</VAR
  12629. ></DT
  12630. ><DD
  12631. ><P
  12632. >          Sets the value of the specified directive.
  12633.          Can be used only with <TT
  12634. CLASS="constant"
  12635. ><B
  12636. >PHP_INI_ALL</B
  12637. ></TT
  12638. > and <TT
  12639. CLASS="constant"
  12640. ><B
  12641. >PHP_INI_PERDIR</B
  12642. ></TT
  12643. > type directives.
  12644.          To clear a previously set value use <VAR
  12645. CLASS="literal"
  12646. >none</VAR
  12647. > as the value.
  12648.         </P
  12649. ><DIV
  12650. CLASS="note"
  12651. ><BLOCKQUOTE
  12652. CLASS="note"
  12653. ><P
  12654. ><B
  12655. >Note: </B
  12656. >
  12657.           Don't use <SPAN
  12658. CLASS="systemitem"
  12659. >php_value</SPAN
  12660. > to set boolean values.
  12661.           <SPAN
  12662. CLASS="systemitem"
  12663. >php_flag</SPAN
  12664. > (see below) should be used instead.
  12665.          </P
  12666. ></BLOCKQUOTE
  12667. ></DIV
  12668. ></DD
  12669. ><DT
  12670. ><SPAN
  12671. CLASS="systemitem"
  12672. >php_flag</SPAN
  12673. >
  12674.         <VAR
  12675. CLASS="parameter"
  12676. >name</VAR
  12677. >
  12678.         <VAR
  12679. CLASS="parameter"
  12680. >on|off</VAR
  12681. ></DT
  12682. ><DD
  12683. ><P
  12684. >          Used to set a boolean configuration directive.
  12685.          Can be used only with <TT
  12686. CLASS="constant"
  12687. ><B
  12688. >PHP_INI_ALL</B
  12689. ></TT
  12690. > and
  12691.          <TT
  12692. CLASS="constant"
  12693. ><B
  12694. >PHP_INI_PERDIR</B
  12695. ></TT
  12696. > type directives.
  12697.         </P
  12698. ></DD
  12699. ><DT
  12700. ><SPAN
  12701. CLASS="systemitem"
  12702. >php_admin_value</SPAN
  12703. >
  12704.         <VAR
  12705. CLASS="parameter"
  12706. >name</VAR
  12707. >
  12708.         <VAR
  12709. CLASS="parameter"
  12710. >value</VAR
  12711. ></DT
  12712. ><DD
  12713. ><P
  12714. >          Sets the value of the specified directive.
  12715.          This <SPAN
  12716. CLASS="emphasis"
  12717. ><I
  12718. CLASS="emphasis"
  12719. >can not be used</I
  12720. ></SPAN
  12721. > in <TT
  12722. CLASS="filename"
  12723. >.htaccess</TT
  12724. > files.
  12725.          Any directive type set with <SPAN
  12726. CLASS="systemitem"
  12727. >php_admin_value</SPAN
  12728. >
  12729.          can not be overridden by <TT
  12730. CLASS="filename"
  12731. >.htaccess</TT
  12732. > or virtualhost directives.
  12733.          To clear a previously set value use <VAR
  12734. CLASS="literal"
  12735. >none</VAR
  12736. > as the value.
  12737.         </P
  12738. ></DD
  12739. ><DT
  12740. ><SPAN
  12741. CLASS="systemitem"
  12742. >php_admin_flag</SPAN
  12743. >
  12744.         <VAR
  12745. CLASS="parameter"
  12746. >name</VAR
  12747. >
  12748.         <VAR
  12749. CLASS="parameter"
  12750. >on|off</VAR
  12751. ></DT
  12752. ><DD
  12753. ><P
  12754. >          Used to set a boolean configuration directive.
  12755.          This <SPAN
  12756. CLASS="emphasis"
  12757. ><I
  12758. CLASS="emphasis"
  12759. >can not be used</I
  12760. ></SPAN
  12761. > in <TT
  12762. CLASS="filename"
  12763. >.htaccess</TT
  12764. > files.
  12765.          Any directive type set with <SPAN
  12766. CLASS="systemitem"
  12767. >php_admin_flag</SPAN
  12768. >
  12769.          can not be overridden by <TT
  12770. CLASS="filename"
  12771. >.htaccess</TT
  12772. > or virtualhost directives.
  12773.         </P
  12774. ></DD
  12775. ></DL
  12776. ></DIV
  12777. >
  12778.     </P
  12779. ><P
  12780. >      <TABLE
  12781. WIDTH="100%"
  12782. BORDER="0"
  12783. CELLPADDING="0"
  12784. CELLSPACING="0"
  12785. CLASS="EXAMPLE"
  12786. ><TR
  12787. ><TD
  12788. ><DIV
  12789. CLASS="example"
  12790. ><A
  12791. NAME="AEN2457"
  12792. ></A
  12793. ><P
  12794. ><B
  12795. >Example 9-2. Apache configuration example</B
  12796. ></P
  12797. ><TABLE
  12798. BORDER="0"
  12799. BGCOLOR="#E0E0E0"
  12800. CELLPADDING="5"
  12801. ><TR
  12802. ><TD
  12803. ><PRE
  12804. CLASS="ini"
  12805. ><IfModule mod_php5.c>
  12806.   php_value include_path ".:/usr/local/lib/php"
  12807.   php_admin_flag safe_mode on
  12808. </IfModule>
  12809. <IfModule mod_php4.c>
  12810.   php_value include_path ".:/usr/local/lib/php"
  12811.   php_admin_flag safe_mode on
  12812. </IfModule>
  12813. <IfModule mod_php3.c>
  12814.   php3_include_path ".:/usr/local/lib/php"
  12815.   php3_safe_mode on
  12816. </IfModule></PRE
  12817. ></TD
  12818. ></TR
  12819. ></TABLE
  12820. ></DIV
  12821. ></TD
  12822. ></TR
  12823. ></TABLE
  12824. >
  12825.     </P
  12826. ><DIV
  12827. CLASS="caution"
  12828. ><P
  12829. ></P
  12830. ><TABLE
  12831. CLASS="caution"
  12832. BORDER="1"
  12833. WIDTH="100%"
  12834. ><TR
  12835. ><TD
  12836. ALIGN="CENTER"
  12837. ><B
  12838. >Caution</B
  12839. ></TD
  12840. ></TR
  12841. ><TR
  12842. ><TD
  12843. ALIGN="LEFT"
  12844. ><P
  12845. >       PHP constants do not exist outside of PHP. For example, in 
  12846.       <TT
  12847. CLASS="filename"
  12848. >httpd.conf</TT
  12849. > you can not use PHP constants 
  12850.       such as <TT
  12851. CLASS="constant"
  12852. ><B
  12853. >E_ALL</B
  12854. ></TT
  12855. > or <TT
  12856. CLASS="constant"
  12857. ><B
  12858. >E_NOTICE</B
  12859. ></TT
  12860. > 
  12861.       to set the <A
  12862. HREF="#ini.error-reporting"
  12863. >error_reporting</A
  12864. > 
  12865.       directive as they will have no meaning and will evaluate to
  12866.       <SPAN
  12867. CLASS="emphasis"
  12868. ><I
  12869. CLASS="emphasis"
  12870. >0</I
  12871. ></SPAN
  12872. >. Use the associated bitmask values instead.
  12873.       These constants can be used in <TT
  12874. CLASS="filename"
  12875. >php.ini</TT
  12876. >
  12877.      </P
  12878. ></TD
  12879. ></TR
  12880. ></TABLE
  12881. ></DIV
  12882. ></DIV
  12883. ><DIV
  12884. CLASS="sect2"
  12885. ><HR><H3
  12886. CLASS="sect2"
  12887. ><A
  12888. NAME="configuration.changes.windows"
  12889. >Changing PHP configuration via the Windows registry</A
  12890. ></H3
  12891. ><P
  12892. >       When running PHP on Windows, the configuration values can be
  12893.       modified on a per-directory basis using the Windows registry. The
  12894.       configuration values are stored in the registry key 
  12895.       <VAR
  12896. CLASS="literal"
  12897. >HKLM\SOFTWARE\PHP\Per Directory Values</VAR
  12898. >, 
  12899.       in the sub-keys corresponding to the path names. For example, configuration 
  12900.       values for the directory <VAR
  12901. CLASS="literal"
  12902. >c:\inetpub\wwwroot</VAR
  12903. > would
  12904.       be stored in the key <VAR
  12905. CLASS="literal"
  12906. >HKLM\SOFTWARE\PHP\Per Directory
  12907.       Values\c\inetpub\wwwroot</VAR
  12908. >. The settings for the
  12909.       directory would be active for any script running from this
  12910.       directory or any subdirectory of it. The values under the key
  12911.       should have the name of the PHP configuration directive and the
  12912.       string value. PHP constants in the values are not parsed. 
  12913.      </P
  12914. ></DIV
  12915. ><DIV
  12916. CLASS="sect2"
  12917. ><HR><H3
  12918. CLASS="sect2"
  12919. ><A
  12920. NAME="configuration.changes.other"
  12921. >Other interfaces to PHP</A
  12922. ></H3
  12923. ><P
  12924. >      Regardless of how you run PHP, you can change certain values at runtime
  12925.      of your scripts through <A
  12926. HREF="#function.ini-set"
  12927. ><B
  12928. CLASS="function"
  12929. >ini_set()</B
  12930. ></A
  12931. >. See the documentation
  12932.      on the <A
  12933. HREF="#function.ini-set"
  12934. ><B
  12935. CLASS="function"
  12936. >ini_set()</B
  12937. ></A
  12938. > page for more information.
  12939.     </P
  12940. ><P
  12941. >      If you are interested in a complete list of configuration settings
  12942.      on your system with their current values, you can execute the
  12943.      <A
  12944. HREF="#function.phpinfo"
  12945. ><B
  12946. CLASS="function"
  12947. >phpinfo()</B
  12948. ></A
  12949. > function, and review the resulting
  12950.      page. You can also access the values of individual configuration
  12951.      directives at runtime using <A
  12952. HREF="#function.ini-get"
  12953. ><B
  12954. CLASS="function"
  12955. >ini_get()</B
  12956. ></A
  12957. > or
  12958.      <A
  12959. HREF="#function.get-cfg-var"
  12960. ><B
  12961. CLASS="function"
  12962. >get_cfg_var()</B
  12963. ></A
  12964. >.
  12965.     </P
  12966. ></DIV
  12967. ></DIV
  12968. ></DIV
  12969. ></DIV
  12970. ><DIV
  12971. CLASS="PART"
  12972. ><A
  12973. NAME="langref"
  12974. ></A
  12975. ><DIV
  12976. CLASS="TITLEPAGE"
  12977. ><H1
  12978. CLASS="title"
  12979. >III. Language Reference</H1
  12980. ><DIV
  12981. CLASS="TOC"
  12982. ><DL
  12983. ><DT
  12984. ><B
  12985. >Table of Contents</B
  12986. ></DT
  12987. ><DT
  12988. >10. <A
  12989. HREF="#language.basic-syntax"
  12990. >Basic syntax</A
  12991. ></DT
  12992. ><DT
  12993. >11. <A
  12994. HREF="#language.types"
  12995. >Types</A
  12996. ></DT
  12997. ><DT
  12998. >12. <A
  12999. HREF="#language.variables"
  13000. >Variables</A
  13001. ></DT
  13002. ><DT
  13003. >13. <A
  13004. HREF="#language.constants"
  13005. >Constants</A
  13006. ></DT
  13007. ><DT
  13008. >14. <A
  13009. HREF="#language.expressions"
  13010. >Expressions</A
  13011. ></DT
  13012. ><DT
  13013. >15. <A
  13014. HREF="#language.operators"
  13015. >Operators</A
  13016. ></DT
  13017. ><DT
  13018. >16. <A
  13019. HREF="#language.control-structures"
  13020. >Control Structures</A
  13021. ></DT
  13022. ><DT
  13023. >17. <A
  13024. HREF="#language.functions"
  13025. >Functions</A
  13026. ></DT
  13027. ><DT
  13028. >18. <A
  13029. HREF="#language.oop"
  13030. >Classes and Objects (PHP 4)</A
  13031. ></DT
  13032. ><DT
  13033. >19. <A
  13034. HREF="#language.oop5"
  13035. >Classes and Objects (PHP 5)</A
  13036. ></DT
  13037. ><DT
  13038. >20. <A
  13039. HREF="#language.exceptions"
  13040. >Exceptions</A
  13041. ></DT
  13042. ><DT
  13043. >21. <A
  13044. HREF="#language.references"
  13045. >References Explained</A
  13046. ></DT
  13047. ></DL
  13048. ></DIV
  13049. ></DIV
  13050. ><DIV
  13051. CLASS="chapter"
  13052. ><HR><H1
  13053. ><A
  13054. NAME="language.basic-syntax"
  13055. >Chapter 10. Basic syntax</A
  13056. ></H1
  13057. ><DIV
  13058. CLASS="sect1"
  13059. ><H2
  13060. CLASS="sect1"
  13061. ><A
  13062. NAME="language.basic-syntax.phpmode"
  13063. >Escaping from HTML</A
  13064. ></H2
  13065. ><P
  13066. >     When PHP parses a file, it simply passes the text of the file
  13067.     through until it encounters one of the special tags which tell it
  13068.     to start interpreting the text as PHP code. The parser then
  13069.     executes all the code it finds, up until it runs into a PHP
  13070.     closing tag, which tells the parser to just start passing the text
  13071.     through again. This is the mechanism which allows you to embed PHP
  13072.     code inside HTML: everything outside the PHP tags is left utterly
  13073.     alone, while everything inside is parsed as code.
  13074.    </P
  13075. ><P
  13076. >     There are four sets of tags which can be used to denote blocks of
  13077.     PHP code. Of these, only two (<?php. . .?> and <script
  13078.     language="php">. . .</script>) are always available; the
  13079.     others can be turned on or off from the
  13080.     <TT
  13081. CLASS="filename"
  13082. >php.ini</TT
  13083. > configuration file. While the
  13084.     short-form tags and ASP-style tags may be convenient, they are not
  13085.     as portable as the longer versions. Also, if you intend to embed
  13086.     PHP code in XML or XHTML, you will need to use the
  13087.     <?php. . .?> form to conform to the XML.
  13088.    </P
  13089. ><P
  13090. >     The tags supported by PHP are:
  13091.    </P
  13092. ><P
  13093. >      <TABLE
  13094. WIDTH="100%"
  13095. BORDER="0"
  13096. CELLPADDING="0"
  13097. CELLSPACING="0"
  13098. CLASS="EXAMPLE"
  13099. ><TR
  13100. ><TD
  13101. ><DIV
  13102. CLASS="example"
  13103. ><A
  13104. NAME="AEN2494"
  13105. ></A
  13106. ><P
  13107. ><B
  13108. >Example 10-1. Ways of escaping from HTML</B
  13109. ></P
  13110. ><TABLE
  13111. BORDER="0"
  13112. BGCOLOR="#E0E0E0"
  13113. CELLPADDING="5"
  13114. ><TR
  13115. ><TD
  13116. ><PRE
  13117. CLASS="php"
  13118. >1.  <?php echo("if you want to serve XHTML or XML documents, do like this\n"); ?>
  13119.  
  13120. 2.  <? echo ("this is the simplest, an SGML processing instruction\n"); ?>
  13121.     <?= expression ?> This is a shortcut for "<? echo expression ?>"
  13122.     
  13123. 3.  <script language="php">
  13124.         echo ("some editors (like FrontPage) don't
  13125.               like processing instructions");
  13126.     </script>
  13127.  
  13128. 4.  <% echo ("You may optionally use ASP-style tags"); %>
  13129.     <%= $variable; # This is a shortcut for "<% echo . . ." %></PRE
  13130. ></TD
  13131. ></TR
  13132. ></TABLE
  13133. ></DIV
  13134. ></TD
  13135. ></TR
  13136. ></TABLE
  13137. >
  13138.     </P
  13139. ><P
  13140. >     The first way, <?php. . .?>, is the preferred method, as it
  13141.     allows the use of PHP in XML-conformant code such as XHTML.
  13142.    </P
  13143. ><P
  13144. >     The second way is not available always. Short tags are available
  13145.     only when they have been enabled. This can be done via the
  13146.     <B
  13147. CLASS="function"
  13148. >short_tags()</B
  13149. > function (PHP 3 only), by enabling
  13150.     the <A
  13151. HREF="#ini.short-open-tag"
  13152. >short_open_tag</A
  13153. >
  13154.     configuration setting in the PHP config file, or by compiling PHP
  13155.     with the <VAR
  13156. CLASS="option"
  13157. >--enable-short-tags</VAR
  13158. > option to
  13159.     <B
  13160. CLASS="command"
  13161. >configure</B
  13162. >. Even if it is enabled by default in
  13163.     <TT
  13164. CLASS="filename"
  13165. >php.ini-dist</TT
  13166. >, use of short tags are discouraged.
  13167.    </P
  13168. ><P
  13169. >     The third way is always available and safe like the first one. However,
  13170.     the first is the preferred and most used one.
  13171.    </P
  13172. ><P
  13173. >     The fourth way is only available if <SPAN
  13174. CLASS="productname"
  13175. >ASP</SPAN
  13176. > 
  13177.     tags have been enabled using the <A
  13178. HREF="#ini.asp-tags"
  13179. >asp_tags</A
  13180. >
  13181.     configuration setting.
  13182.     <DIV
  13183. CLASS="note"
  13184. ><BLOCKQUOTE
  13185. CLASS="note"
  13186. ><P
  13187. ><B
  13188. >Note: </B
  13189. >Support for <SPAN
  13190. CLASS="productname"
  13191. >ASP</SPAN
  13192. > tags was added in 3.0.4.</P
  13193. ></BLOCKQUOTE
  13194. ></DIV
  13195. >
  13196.    </P
  13197. ><P
  13198. >     <DIV
  13199. CLASS="note"
  13200. ><BLOCKQUOTE
  13201. CLASS="note"
  13202. ><P
  13203. ><B
  13204. >Note: </B
  13205. >
  13206.       Using short tags should be avoided when developing applications
  13207.       or libraries that are meant for redistribution, or deployment on
  13208.       PHP servers which are not under your control, because short tags
  13209.       may not be supported on the target server.  For portable,
  13210.       redistributable code, be sure not to use short tags.
  13211.      </P
  13212. ></BLOCKQUOTE
  13213. ></DIV
  13214. >
  13215.    </P
  13216. ><P
  13217. >     The closing tag for the block will include the immediately
  13218.     trailing newline if one is present. Also, the closing tag
  13219.     automatically implies a semicolon; you do not need to have a
  13220.     semicolon terminating the last line of a PHP block.
  13221.     Closing tag of a PHP block at the end of a file is optional.
  13222.    </P
  13223. ><P
  13224. >     PHP allows you to use structures like this:
  13225.     <TABLE
  13226. WIDTH="100%"
  13227. BORDER="0"
  13228. CELLPADDING="0"
  13229. CELLSPACING="0"
  13230. CLASS="EXAMPLE"
  13231. ><TR
  13232. ><TD
  13233. ><DIV
  13234. CLASS="example"
  13235. ><A
  13236. NAME="AEN2516"
  13237. ></A
  13238. ><P
  13239. ><B
  13240. >Example 10-2. Advanced escaping</B
  13241. ></P
  13242. ><TABLE
  13243. BORDER="0"
  13244. BGCOLOR="#E0E0E0"
  13245. CELLPADDING="5"
  13246. ><TR
  13247. ><TD
  13248. ><PRE
  13249. CLASS="php"
  13250. ><?php
  13251. if ($expression) { 
  13252.     ?>
  13253.     <strong>This is true.</strong>
  13254.     <?php 
  13255. } else { 
  13256.     ?>
  13257.     <strong>This is false.</strong>
  13258.     <?php 
  13259. }
  13260. ?></PRE
  13261. ></TD
  13262. ></TR
  13263. ></TABLE
  13264. ></DIV
  13265. ></TD
  13266. ></TR
  13267. ></TABLE
  13268. >
  13269.     This works as expected, because when PHP hits the ?> closing
  13270.     tags, it simply starts outputting whatever it finds until it hits
  13271.     another opening tag. The example given here is contrived, of
  13272.     course, but for outputting large blocks of text, dropping out of
  13273.     PHP parsing mode is generally more efficient than sending all of
  13274.     the text through <A
  13275. HREF="#function.echo"
  13276. ><B
  13277. CLASS="function"
  13278. >echo()</B
  13279. ></A
  13280. > or
  13281.     <A
  13282. HREF="#function.print"
  13283. ><B
  13284. CLASS="function"
  13285. >print()</B
  13286. ></A
  13287. > or somesuch.
  13288.    </P
  13289. ></DIV
  13290. ><DIV
  13291. CLASS="sect1"
  13292. ><HR><H2
  13293. CLASS="sect1"
  13294. ><A
  13295. NAME="language.basic-syntax.instruction-separation"
  13296. >Instruction separation</A
  13297. ></H2
  13298. ><P
  13299. >     Instructions are separated the same as in C or Perl - terminate
  13300.     each statement with a semicolon.
  13301.    </P
  13302. ><P
  13303. >     The closing tag (?>) also implies the end of the statement, so
  13304.     the following are equivalent:
  13305.  
  13306.     <DIV
  13307. CLASS="informalexample"
  13308. ><P
  13309. ></P
  13310. ><A
  13311. NAME="AEN2525"
  13312. ></A
  13313. ><TABLE
  13314. BORDER="0"
  13315. BGCOLOR="#E0E0E0"
  13316. CELLPADDING="5"
  13317. ><TR
  13318. ><TD
  13319. ><PRE
  13320. CLASS="php"
  13321. ><?php
  13322.     echo "This is a test";
  13323. ?>
  13324.  
  13325. <?php echo "This is a test" ?></PRE
  13326. ></TD
  13327. ></TR
  13328. ></TABLE
  13329. ><P
  13330. ></P
  13331. ></DIV
  13332. >
  13333.    </P
  13334. ></DIV
  13335. ><DIV
  13336. CLASS="sect1"
  13337. ><HR><H2
  13338. CLASS="sect1"
  13339. ><A
  13340. NAME="language.basic-syntax.comments"
  13341. >Comments</A
  13342. ></H2
  13343. ><P
  13344. >     PHP supports 'C', 'C++' and Unix shell-style comments. For example:
  13345.  
  13346.     <DIV
  13347. CLASS="informalexample"
  13348. ><P
  13349. ></P
  13350. ><A
  13351. NAME="AEN2530"
  13352. ></A
  13353. ><TABLE
  13354. BORDER="0"
  13355. BGCOLOR="#E0E0E0"
  13356. CELLPADDING="5"
  13357. ><TR
  13358. ><TD
  13359. ><PRE
  13360. CLASS="php"
  13361. ><?php
  13362.     echo "This is a test"; // This is a one-line c++ style comment
  13363.     /* This is a multi line comment
  13364.        yet another line of comment */
  13365.     echo "This is yet another test";
  13366.     echo "One Final Test"; # This is shell-style style comment
  13367. ?></PRE
  13368. ></TD
  13369. ></TR
  13370. ></TABLE
  13371. ><P
  13372. ></P
  13373. ></DIV
  13374. >
  13375.    </P
  13376. ><P
  13377. >     The "one-line" comment styles actually only comment to the end of
  13378.     the line or the current block of PHP code, whichever comes
  13379.     first.
  13380.    </P
  13381. ><P
  13382. >     <DIV
  13383. CLASS="informalexample"
  13384. ><P
  13385. ></P
  13386. ><A
  13387. NAME="AEN2534"
  13388. ></A
  13389. ><TABLE
  13390. BORDER="0"
  13391. BGCOLOR="#E0E0E0"
  13392. CELLPADDING="5"
  13393. ><TR
  13394. ><TD
  13395. ><PRE
  13396. CLASS="php"
  13397. ><h1>This is an <?php # echo "simple";?> example.</h1>
  13398. <p>The header above will say 'This is an example'.</PRE
  13399. ></TD
  13400. ></TR
  13401. ></TABLE
  13402. ><P
  13403. ></P
  13404. ></DIV
  13405. > 
  13406.    </P
  13407. ><P
  13408. >     You should be careful not to nest 'C' style comments, which can
  13409.     happen when commenting out large blocks.
  13410.    </P
  13411. ><P
  13412. >     <DIV
  13413. CLASS="informalexample"
  13414. ><P
  13415. ></P
  13416. ><A
  13417. NAME="AEN2538"
  13418. ></A
  13419. ><TABLE
  13420. BORDER="0"
  13421. BGCOLOR="#E0E0E0"
  13422. CELLPADDING="5"
  13423. ><TR
  13424. ><TD
  13425. ><PRE
  13426. CLASS="php"
  13427. ><?php
  13428.  /* 
  13429.     echo "This is a test"; /* This comment will cause a problem */
  13430.  */
  13431. ?></PRE
  13432. ></TD
  13433. ></TR
  13434. ></TABLE
  13435. ><P
  13436. ></P
  13437. ></DIV
  13438. >
  13439.    </P
  13440. ><P
  13441. >     The one-line comment styles actually only comment to the end
  13442.     of the line or the current block of PHP code, whichever comes first.
  13443.     This means that HTML code after <VAR
  13444. CLASS="literal"
  13445. >// ?></VAR
  13446. > WILL be printed:
  13447.     ?> skips out of the PHP mode and returns to HTML mode, and
  13448.     <VAR
  13449. CLASS="literal"
  13450. >//</VAR
  13451. > cannot influence that.
  13452.     If <A
  13453. HREF="#ini.asp-tags"
  13454. >asp_tags</A
  13455. > configuration directive
  13456.     is enabled, it behaves the same with <VAR
  13457. CLASS="literal"
  13458. >// %></VAR
  13459. >.
  13460.    </P
  13461. ></DIV
  13462. ></DIV
  13463. ><DIV
  13464. CLASS="chapter"
  13465. ><HR><H1
  13466. ><A
  13467. NAME="language.types"
  13468. >Chapter 11. Types</A
  13469. ></H1
  13470. ><DIV
  13471. CLASS="sect1"
  13472. ><H2
  13473. CLASS="sect1"
  13474. ><A
  13475. NAME="language.types.intro"
  13476. >Introduction</A
  13477. ></H2
  13478. ><P
  13479. >    PHP supports eight primitive types.
  13480.   </P
  13481. ><P
  13482. >    Four scalar types:
  13483.  
  13484.    <P
  13485. ></P
  13486. ><UL
  13487. ><LI
  13488. ><P
  13489. >       <A
  13490. HREF="#language.types.boolean"
  13491. ><B
  13492. CLASS="type"
  13493. >boolean</B
  13494. ></A
  13495. >
  13496.      </P
  13497. ></LI
  13498. ><LI
  13499. ><P
  13500. >       <A
  13501. HREF="#language.types.integer"
  13502. ><B
  13503. CLASS="type"
  13504. >integer</B
  13505. ></A
  13506. >
  13507.      </P
  13508. ></LI
  13509. ><LI
  13510. ><P
  13511. >       <A
  13512. HREF="#language.types.float"
  13513. ><B
  13514. CLASS="type"
  13515. >float</B
  13516. ></A
  13517. > (floating-point number, aka '<A
  13518. HREF="#language.types.float"
  13519. ><B
  13520. CLASS="type"
  13521. >double</B
  13522. ></A
  13523. >')
  13524.      </P
  13525. ></LI
  13526. ><LI
  13527. ><P
  13528. >       <A
  13529. HREF="#language.types.string"
  13530. ><B
  13531. CLASS="type"
  13532. >string</B
  13533. ></A
  13534. >
  13535.      </P
  13536. ></LI
  13537. ></UL
  13538. >
  13539.  
  13540.    Two compound types:
  13541.  
  13542.    <P
  13543. ></P
  13544. ><UL
  13545. ><LI
  13546. ><P
  13547. >       <A
  13548. HREF="#language.types.array"
  13549. ><B
  13550. CLASS="type"
  13551. >array</B
  13552. ></A
  13553. >
  13554.      </P
  13555. ></LI
  13556. ><LI
  13557. ><P
  13558. >       <A
  13559. HREF="#language.types.object"
  13560. ><B
  13561. CLASS="type"
  13562. >object</B
  13563. ></A
  13564. >
  13565.      </P
  13566. ></LI
  13567. ></UL
  13568. >
  13569.  
  13570.    And finally two special types:
  13571.  
  13572.    <P
  13573. ></P
  13574. ><UL
  13575. ><LI
  13576. ><P
  13577. >       <A
  13578. HREF="#language.types.resource"
  13579. ><B
  13580. CLASS="type"
  13581. >resource</B
  13582. ></A
  13583. >
  13584.      </P
  13585. ></LI
  13586. ><LI
  13587. ><P
  13588. >       <A
  13589. HREF="#language.types.null"
  13590. ><B
  13591. CLASS="type"
  13592. >NULL</B
  13593. ></A
  13594. >
  13595.      </P
  13596. ></LI
  13597. ></UL
  13598. >
  13599.  
  13600.    This manual also introduces some 
  13601.    <A
  13602. HREF="#language.pseudo-types"
  13603. >pseudo-types</A
  13604. > 
  13605.    for readability reasons:
  13606.  
  13607.    <P
  13608. ></P
  13609. ><UL
  13610. ><LI
  13611. ><P
  13612. >       <A
  13613. HREF="#language.types.mixed"
  13614. ><B
  13615. CLASS="type"
  13616. >mixed</B
  13617. ></A
  13618. >
  13619.      </P
  13620. ></LI
  13621. ><LI
  13622. ><P
  13623. >       <A
  13624. HREF="#language.types.number"
  13625. ><B
  13626. CLASS="type"
  13627. >number</B
  13628. ></A
  13629. >
  13630.      </P
  13631. ></LI
  13632. ><LI
  13633. ><P
  13634. >       <A
  13635. HREF="#language.types.callback"
  13636. ><B
  13637. CLASS="type"
  13638. >callback</B
  13639. ></A
  13640. >
  13641.      </P
  13642. ></LI
  13643. ></UL
  13644. >
  13645.    You may also find some references to the type "double". Consider
  13646.    double the same as float, the two names exist only for historic
  13647.    reasons. 
  13648.   </P
  13649. ><P
  13650. >    The type of a variable is usually not set by the programmer;
  13651.    rather, it is decided at runtime by PHP depending on the context in
  13652.    which that variable is used.
  13653.   </P
  13654. ><DIV
  13655. CLASS="note"
  13656. ><BLOCKQUOTE
  13657. CLASS="note"
  13658. ><P
  13659. ><B
  13660. >Note: </B
  13661. >
  13662.     If you want to check out the type and value of a certain <A
  13663. HREF="#language.expressions"
  13664. >expression</A
  13665. >, use
  13666.     <A
  13667. HREF="#function.var-dump"
  13668. ><B
  13669. CLASS="function"
  13670. >var_dump()</B
  13671. ></A
  13672. >.
  13673.    </P
  13674. ><P
  13675. ><B
  13676. >Note: </B
  13677. >
  13678.     If you simply want a human-readable representation of the type for
  13679.     debugging, use <A
  13680. HREF="#function.gettype"
  13681. ><B
  13682. CLASS="function"
  13683. >gettype()</B
  13684. ></A
  13685. >. To check for a certain type,
  13686.     do <SPAN
  13687. CLASS="emphasis"
  13688. ><I
  13689. CLASS="emphasis"
  13690. >not</I
  13691. ></SPAN
  13692. > use <A
  13693. HREF="#function.gettype"
  13694. ><B
  13695. CLASS="function"
  13696. >gettype()</B
  13697. ></A
  13698. >, but use the
  13699.     <VAR
  13700. CLASS="literal"
  13701. >is_<VAR
  13702. CLASS="replaceable"
  13703. >type</VAR
  13704. ></VAR
  13705. > functions. Some
  13706.     examples:
  13707.     <DIV
  13708. CLASS="informalexample"
  13709. ><P
  13710. ></P
  13711. ><A
  13712. NAME="AEN2601"
  13713. ></A
  13714. ><TABLE
  13715. BORDER="0"
  13716. BGCOLOR="#E0E0E0"
  13717. CELLPADDING="5"
  13718. ><TR
  13719. ><TD
  13720. ><PRE
  13721. CLASS="php"
  13722. ><?php
  13723. $bool = TRUE;   // a boolean
  13724. $str  = "foo";  // a string
  13725. $int  = 12;     // an integer
  13726.  
  13727. echo gettype($bool); // prints out "boolean"
  13728. echo gettype($str);  // prints out "string"
  13729.  
  13730. // If this is an integer, increment it by four
  13731. if (is_int($int)) {
  13732.     $int += 4;
  13733. }
  13734.  
  13735. // If $bool is a string, print it out
  13736. // (does not print out anything)
  13737. if (is_string($bool)) {
  13738.     echo "String: $bool";
  13739. }
  13740. ?></PRE
  13741. ></TD
  13742. ></TR
  13743. ></TABLE
  13744. ><P
  13745. ></P
  13746. ></DIV
  13747. >
  13748.    </P
  13749. ></BLOCKQUOTE
  13750. ></DIV
  13751. ><P
  13752. >    If you would like to force a variable to be converted to a certain
  13753.    type, you may either <A
  13754. HREF="#language.types.typecasting"
  13755. >cast</A
  13756. > the variable or
  13757.    use the <A
  13758. HREF="#function.settype"
  13759. ><B
  13760. CLASS="function"
  13761. >settype()</B
  13762. ></A
  13763. > function on it.
  13764.   </P
  13765. ><P
  13766. >    Note that a variable may be evaluated with different values in certain
  13767.    situations, depending on what type it is at the time. For more
  13768.    information, see the section on <A
  13769. HREF="#language.types.type-juggling"
  13770. >Type Juggling</A
  13771. >.  Also, you 
  13772.    may be interested in viewing 
  13773.    <A
  13774. HREF="#types.comparisons"
  13775. >the type comparison tables</A
  13776. >,
  13777.    as they show examples of various type related comparisons.
  13778.   </P
  13779. ></DIV
  13780. ><DIV
  13781. CLASS="sect1"
  13782. ><HR><H2
  13783. CLASS="sect1"
  13784. ><A
  13785. NAME="language.types.boolean"
  13786. >Booleans</A
  13787. ></H2
  13788. ><P
  13789. >      This is the easiest type. A <A
  13790. HREF="#language.types.boolean"
  13791. ><B
  13792. CLASS="type"
  13793. >boolean</B
  13794. ></A
  13795. > expresses a 
  13796.      truth value. It can be either <TT
  13797. CLASS="constant"
  13798. ><B
  13799. >TRUE</B
  13800. ></TT
  13801. > or <TT
  13802. CLASS="constant"
  13803. ><B
  13804. >FALSE</B
  13805. ></TT
  13806. >. 
  13807.     </P
  13808. ><DIV
  13809. CLASS="note"
  13810. ><BLOCKQUOTE
  13811. CLASS="note"
  13812. ><P
  13813. ><B
  13814. >Note: </B
  13815. >
  13816.       The boolean type was introduced in PHP 4.
  13817.      </P
  13818. ></BLOCKQUOTE
  13819. ></DIV
  13820. ><DIV
  13821. CLASS="sect2"
  13822. ><HR><H3
  13823. CLASS="sect2"
  13824. ><A
  13825. NAME="language.types.boolean.syntax"
  13826. >Syntax</A
  13827. ></H3
  13828. ><P
  13829. >       To specify a boolean literal, use either the keyword <TT
  13830. CLASS="constant"
  13831. ><B
  13832. >TRUE</B
  13833. ></TT
  13834. > 
  13835.       or <TT
  13836. CLASS="constant"
  13837. ><B
  13838. >FALSE</B
  13839. ></TT
  13840. >. Both are case-insensitive.
  13841.       <DIV
  13842. CLASS="informalexample"
  13843. ><P
  13844. ></P
  13845. ><A
  13846. NAME="AEN2622"
  13847. ></A
  13848. ><TABLE
  13849. BORDER="0"
  13850. BGCOLOR="#E0E0E0"
  13851. CELLPADDING="5"
  13852. ><TR
  13853. ><TD
  13854. ><PRE
  13855. CLASS="php"
  13856. ><?php
  13857. $foo = True; // assign the value TRUE to $foo
  13858. ?></PRE
  13859. ></TD
  13860. ></TR
  13861. ></TABLE
  13862. ><P
  13863. ></P
  13864. ></DIV
  13865. >
  13866.      </P
  13867. ><P
  13868. >       Usually you 
  13869.       use some kind of <A
  13870. HREF="#language.operators"
  13871. >operator</A
  13872. >
  13873.       which returns a <A
  13874. HREF="#language.types.boolean"
  13875. ><B
  13876. CLASS="type"
  13877. >boolean</B
  13878. ></A
  13879. > value, and then pass it 
  13880.       on to a <A
  13881. HREF="#language.control-structures"
  13882. >control
  13883.       structure</A
  13884. >.
  13885.       <DIV
  13886. CLASS="informalexample"
  13887. ><P
  13888. ></P
  13889. ><A
  13890. NAME="AEN2628"
  13891. ></A
  13892. ><TABLE
  13893. BORDER="0"
  13894. BGCOLOR="#E0E0E0"
  13895. CELLPADDING="5"
  13896. ><TR
  13897. ><TD
  13898. ><PRE
  13899. CLASS="php"
  13900. ><?php
  13901. // == is an operator which test
  13902. // equality and returns a boolean
  13903. if ($action == "show_version") {
  13904.     echo "The version is 1.23";
  13905. }
  13906.  
  13907. // this is not necessary...
  13908. if ($show_separators == TRUE) {
  13909.     echo "<hr>\n";
  13910. }
  13911.  
  13912. // ...because you can simply type
  13913. if ($show_separators) {
  13914.     echo "<hr>\n";
  13915. }
  13916. ?></PRE
  13917. ></TD
  13918. ></TR
  13919. ></TABLE
  13920. ><P
  13921. ></P
  13922. ></DIV
  13923. >
  13924.      </P
  13925. ></DIV
  13926. ><DIV
  13927. CLASS="sect2"
  13928. ><HR><H3
  13929. CLASS="sect2"
  13930. ><A
  13931. NAME="language.types.boolean.casting"
  13932. >Converting to boolean</A
  13933. ></H3
  13934. ><P
  13935. >        To explicitly convert a value to <A
  13936. HREF="#language.types.boolean"
  13937. ><B
  13938. CLASS="type"
  13939. >boolean</B
  13940. ></A
  13941. >, use either
  13942.        the <VAR
  13943. CLASS="literal"
  13944. >(bool)</VAR
  13945. > or the <VAR
  13946. CLASS="literal"
  13947. >(boolean)</VAR
  13948. > cast.
  13949.        However, in most cases you do not need to use the cast, since a value
  13950.        will be automatically converted if an operator, function or 
  13951.        control structure requires a <A
  13952. HREF="#language.types.boolean"
  13953. ><B
  13954. CLASS="type"
  13955. >boolean</B
  13956. ></A
  13957. > argument.
  13958.       </P
  13959. ><P
  13960. >        See also <A
  13961. HREF="#language.types.type-juggling"
  13962. >Type Juggling</A
  13963. >.
  13964.       </P
  13965. ><P
  13966. >        When converting to <A
  13967. HREF="#language.types.boolean"
  13968. ><B
  13969. CLASS="type"
  13970. >boolean</B
  13971. ></A
  13972. >, the following values 
  13973.        are considered <TT
  13974. CLASS="constant"
  13975. ><B
  13976. >FALSE</B
  13977. ></TT
  13978. >:
  13979.   
  13980.        <P
  13981. ></P
  13982. ><UL
  13983. ><LI
  13984. ><P
  13985. >the <A
  13986. HREF="#language.types.boolean"
  13987. >boolean</A
  13988. > 
  13989.           <TT
  13990. CLASS="constant"
  13991. ><B
  13992. >FALSE</B
  13993. ></TT
  13994. > itself</P
  13995. ></LI
  13996. ><LI
  13997. ><P
  13998. >the <A
  13999. HREF="#language.types.integer"
  14000. >integer</A
  14001. > 0 (zero) </P
  14002. ></LI
  14003. ><LI
  14004. ><P
  14005. >the <A
  14006. HREF="#language.types.float"
  14007. >float</A
  14008. > 
  14009.          0.0 (zero) </P
  14010. ></LI
  14011. ><LI
  14012. ><P
  14013. >the empty <A
  14014. HREF="#language.types.string"
  14015. >string</A
  14016. >, and the <A
  14017. HREF="#language.types.string"
  14018. >string</A
  14019. >
  14020.            "0"</P
  14021. ></LI
  14022. ><LI
  14023. ><P
  14024. >an <A
  14025. HREF="#language.types.array"
  14026. >array</A
  14027. > 
  14028.          with zero elements</P
  14029. ></LI
  14030. ><LI
  14031. ><P
  14032. >an <A
  14033. HREF="#language.types.object"
  14034. >object</A
  14035. > 
  14036.          with zero member variables (PHP 4 only)</P
  14037. ></LI
  14038. ><LI
  14039. ><P
  14040. >the special type <A
  14041. HREF="#language.types.null"
  14042. >NULL</A
  14043. > (including unset variables)
  14044.          </P
  14045. ></LI
  14046. ></UL
  14047. >
  14048.        
  14049.        Every other value is considered <TT
  14050. CLASS="constant"
  14051. ><B
  14052. >TRUE</B
  14053. ></TT
  14054. > (including any 
  14055.        <A
  14056. HREF="#language.types.resource"
  14057. >resource</A
  14058. >).
  14059.        <DIV
  14060. CLASS="warning"
  14061. ><P
  14062. ></P
  14063. ><TABLE
  14064. CLASS="warning"
  14065. BORDER="1"
  14066. WIDTH="100%"
  14067. ><TR
  14068. ><TD
  14069. ALIGN="CENTER"
  14070. ><B
  14071. >Warning</B
  14072. ></TD
  14073. ></TR
  14074. ><TR
  14075. ><TD
  14076. ALIGN="LEFT"
  14077. ><P
  14078. >          <VAR
  14079. CLASS="literal"
  14080. >-1</VAR
  14081. > is considered  
  14082.          <TT
  14083. CLASS="constant"
  14084. ><B
  14085. >TRUE</B
  14086. ></TT
  14087. >, like any other non-zero (whether negative
  14088.          or positive) number!
  14089.         </P
  14090. ></TD
  14091. ></TR
  14092. ></TABLE
  14093. ></DIV
  14094. >
  14095.        <DIV
  14096. CLASS="informalexample"
  14097. ><P
  14098. ></P
  14099. ><A
  14100. NAME="AEN2672"
  14101. ></A
  14102. ><TABLE
  14103. BORDER="0"
  14104. BGCOLOR="#E0E0E0"
  14105. CELLPADDING="5"
  14106. ><TR
  14107. ><TD
  14108. ><PRE
  14109. CLASS="php"
  14110. ><?php
  14111. var_dump((bool) "");        // bool(false)
  14112. var_dump((bool) 1);         // bool(true)
  14113. var_dump((bool) -2);        // bool(true)
  14114. var_dump((bool) "foo");     // bool(true)
  14115. var_dump((bool) 2.3e5);     // bool(true)
  14116. var_dump((bool) array(12)); // bool(true)
  14117. var_dump((bool) array());   // bool(false)
  14118. var_dump((bool) "false");   // bool(true)
  14119. ?></PRE
  14120. ></TD
  14121. ></TR
  14122. ></TABLE
  14123. ><P
  14124. ></P
  14125. ></DIV
  14126. >
  14127.       </P
  14128. ></DIV
  14129. ></DIV
  14130. ><DIV
  14131. CLASS="sect1"
  14132. ><HR><H2
  14133. CLASS="sect1"
  14134. ><A
  14135. NAME="language.types.integer"
  14136. >Integers</A
  14137. ></H2
  14138. ><P
  14139. >      An <A
  14140. HREF="#language.types.integer"
  14141. ><B
  14142. CLASS="type"
  14143. >integer</B
  14144. ></A
  14145. > is a number of the set 
  14146.      Z = {..., -2, -1, 0, 1, 2, ...}.
  14147.     </P
  14148. ><P
  14149. >      See also:
  14150.      <A
  14151. HREF="#ref.gmp"
  14152. >Arbitrary length integer / GMP</A
  14153. >,
  14154.      <A
  14155. HREF="#language.types.float"
  14156. >Floating point numbers</A
  14157. >, and
  14158.      <A
  14159. HREF="#ref.bc"
  14160. >Arbitrary precision / BCMath</A
  14161. >
  14162.     </P
  14163. ><DIV
  14164. CLASS="sect2"
  14165. ><HR><H3
  14166. CLASS="sect2"
  14167. ><A
  14168. NAME="language.types.integer.syntax"
  14169. >Syntax</A
  14170. ></H3
  14171. ><P
  14172. >       Integers can be specified in decimal (10-based), hexadecimal (16-based)
  14173.       or octal (8-based) notation, optionally preceded by a sign (- or +).
  14174.      </P
  14175. ><P
  14176. >       If you use the octal notation, you must precede the number with a 
  14177.       <VAR
  14178. CLASS="literal"
  14179. >0</VAR
  14180. > (zero), to use hexadecimal notation precede
  14181.       the number with <VAR
  14182. CLASS="literal"
  14183. >0x</VAR
  14184. >.
  14185.       <TABLE
  14186. WIDTH="100%"
  14187. BORDER="0"
  14188. CELLPADDING="0"
  14189. CELLSPACING="0"
  14190. CLASS="EXAMPLE"
  14191. ><TR
  14192. ><TD
  14193. ><DIV
  14194. CLASS="example"
  14195. ><A
  14196. NAME="AEN2688"
  14197. ></A
  14198. ><P
  14199. ><B
  14200. >Example 11-1. Integer literals</B
  14201. ></P
  14202. ><TABLE
  14203. BORDER="0"
  14204. BGCOLOR="#E0E0E0"
  14205. CELLPADDING="5"
  14206. ><TR
  14207. ><TD
  14208. ><PRE
  14209. CLASS="php"
  14210. ><?php
  14211. $a = 1234; // decimal number
  14212. $a = -123; // a negative number
  14213. $a = 0123; // octal number (equivalent to 83 decimal)
  14214. $a = 0x1A; // hexadecimal number (equivalent to 26 decimal)
  14215. ?></PRE
  14216. ></TD
  14217. ></TR
  14218. ></TABLE
  14219. ></DIV
  14220. ></TD
  14221. ></TR
  14222. ></TABLE
  14223. >
  14224.       Formally the possible structure for integer literals is:
  14225.       <DIV
  14226. CLASS="informalexample"
  14227. ><P
  14228. ></P
  14229. ><A
  14230. NAME="AEN2691"
  14231. ></A
  14232. ><TABLE
  14233. BORDER="0"
  14234. BGCOLOR="#E0E0E0"
  14235. CELLPADDING="5"
  14236. ><TR
  14237. ><TD
  14238. ><PRE
  14239. CLASS="programlisting"
  14240. >decimal     : [1-9][0-9]*
  14241.             | 0
  14242.  
  14243. hexadecimal : 0[xX][0-9a-fA-F]+
  14244.  
  14245. octal       : 0[0-7]+
  14246.  
  14247. integer     : [+-]?decimal
  14248.             | [+-]?hexadecimal
  14249.             | [+-]?octal</PRE
  14250. ></TD
  14251. ></TR
  14252. ></TABLE
  14253. ><P
  14254. ></P
  14255. ></DIV
  14256. >
  14257.       The size of an integer is platform-dependent, although a 
  14258.       maximum value of about two billion is the usual value 
  14259.       (that's 32 bits signed). PHP does not support unsigned
  14260.       integers.
  14261.      </P
  14262. ><DIV
  14263. CLASS="warning"
  14264. ><P
  14265. ></P
  14266. ><TABLE
  14267. CLASS="warning"
  14268. BORDER="1"
  14269. WIDTH="100%"
  14270. ><TR
  14271. ><TD
  14272. ALIGN="CENTER"
  14273. ><B
  14274. >Warning</B
  14275. ></TD
  14276. ></TR
  14277. ><TR
  14278. ><TD
  14279. ALIGN="LEFT"
  14280. ><P
  14281. >        If invalid digit is passed to octal integer (i.e. 8 or 9), the rest of
  14282.        the number is ignored.
  14283.        <TABLE
  14284. WIDTH="100%"
  14285. BORDER="0"
  14286. CELLPADDING="0"
  14287. CELLSPACING="0"
  14288. CLASS="EXAMPLE"
  14289. ><TR
  14290. ><TD
  14291. ><DIV
  14292. CLASS="example"
  14293. ><A
  14294. NAME="AEN2695"
  14295. ></A
  14296. ><P
  14297. ><B
  14298. >Example 11-2. Octal weirdness</B
  14299. ></P
  14300. ><TABLE
  14301. BORDER="0"
  14302. BGCOLOR="#E0E0E0"
  14303. CELLPADDING="5"
  14304. ><TR
  14305. ><TD
  14306. ><PRE
  14307. CLASS="php"
  14308. ><?php
  14309. var_dump(01090); // 010 octal = 8 decimal
  14310. ?></PRE
  14311. ></TD
  14312. ></TR
  14313. ></TABLE
  14314. ></DIV
  14315. ></TD
  14316. ></TR
  14317. ></TABLE
  14318. >
  14319.       </P
  14320. ></TD
  14321. ></TR
  14322. ></TABLE
  14323. ></DIV
  14324. ></DIV
  14325. ><DIV
  14326. CLASS="sect2"
  14327. ><HR><H3
  14328. CLASS="sect2"
  14329. ><A
  14330. NAME="language.types.integer.overflow"
  14331. >Integer overflow</A
  14332. ></H3
  14333. ><P
  14334. >       If you specify a number beyond the bounds of the <A
  14335. HREF="#language.types.integer"
  14336. ><B
  14337. CLASS="type"
  14338. >integer</B
  14339. ></A
  14340. >
  14341.       type, it will be interpreted as a <A
  14342. HREF="#language.types.float"
  14343. ><B
  14344. CLASS="type"
  14345. >float</B
  14346. ></A
  14347. > instead. Also, if
  14348.       you perform an operation that results in a number beyond the bounds of
  14349.       the <A
  14350. HREF="#language.types.integer"
  14351. ><B
  14352. CLASS="type"
  14353. >integer</B
  14354. ></A
  14355. > type, a <A
  14356. HREF="#language.types.float"
  14357. ><B
  14358. CLASS="type"
  14359. >float</B
  14360. ></A
  14361. > will be returned
  14362.       instead.
  14363.  
  14364.       <DIV
  14365. CLASS="informalexample"
  14366. ><P
  14367. ></P
  14368. ><A
  14369. NAME="AEN2705"
  14370. ></A
  14371. ><TABLE
  14372. BORDER="0"
  14373. BGCOLOR="#E0E0E0"
  14374. CELLPADDING="5"
  14375. ><TR
  14376. ><TD
  14377. ><PRE
  14378. CLASS="php"
  14379. ><?php
  14380. $large_number =  2147483647;
  14381. var_dump($large_number);
  14382. // output: int(2147483647)
  14383.  
  14384. $large_number =  2147483648;
  14385. var_dump($large_number);
  14386. // output: float(2147483648)
  14387.  
  14388. // this goes also for hexadecimal specified integers:
  14389. var_dump( 0x80000000 );
  14390. // output: float(2147483648)
  14391.  
  14392. $million = 1000000;
  14393. $large_number =  50000 * $million;
  14394. var_dump($large_number);
  14395. // output: float(50000000000)
  14396. ?></PRE
  14397. ></TD
  14398. ></TR
  14399. ></TABLE
  14400. ><P
  14401. ></P
  14402. ></DIV
  14403. >
  14404.       <DIV
  14405. CLASS="warning"
  14406. ><P
  14407. ></P
  14408. ><TABLE
  14409. CLASS="warning"
  14410. BORDER="1"
  14411. WIDTH="100%"
  14412. ><TR
  14413. ><TD
  14414. ALIGN="CENTER"
  14415. ><B
  14416. >Warning</B
  14417. ></TD
  14418. ></TR
  14419. ><TR
  14420. ><TD
  14421. ALIGN="LEFT"
  14422. ><P
  14423. >         Unfortunately, there was a bug in PHP so that this
  14424.         does not always work correctly when there are negative numbers
  14425.         involved. For example: when you do <VAR
  14426. CLASS="literal"
  14427. >-50000 *
  14428.         $million</VAR
  14429. >, the result will be
  14430.         <VAR
  14431. CLASS="literal"
  14432. >-429496728</VAR
  14433. >. However, when both operands are
  14434.         positive there is no problem.
  14435.        </P
  14436. ><P
  14437. >         This is solved in PHP 4.1.0.
  14438.        </P
  14439. ></TD
  14440. ></TR
  14441. ></TABLE
  14442. ></DIV
  14443. >
  14444.      </P
  14445. ><P
  14446. >       There is no integer division operator in PHP.
  14447.       <VAR
  14448. CLASS="literal"
  14449. >1/2</VAR
  14450. > yields the <A
  14451. HREF="#language.types.float"
  14452. ><B
  14453. CLASS="type"
  14454. >float</B
  14455. ></A
  14456. >
  14457.       <VAR
  14458. CLASS="literal"
  14459. >0.5</VAR
  14460. >. You can cast the value to
  14461.       an integer to always round it downwards, or you can
  14462.       use the <A
  14463. HREF="#function.round"
  14464. ><B
  14465. CLASS="function"
  14466. >round()</B
  14467. ></A
  14468. > function.
  14469.       <DIV
  14470. CLASS="informalexample"
  14471. ><P
  14472. ></P
  14473. ><A
  14474. NAME="AEN2717"
  14475. ></A
  14476. ><TABLE
  14477. BORDER="0"
  14478. BGCOLOR="#E0E0E0"
  14479. CELLPADDING="5"
  14480. ><TR
  14481. ><TD
  14482. ><PRE
  14483. CLASS="php"
  14484. ><?php
  14485. var_dump(25/7);         // float(3.5714285714286) 
  14486. var_dump((int) (25/7)); // int(3)
  14487. var_dump(round(25/7));  // float(4) 
  14488. ?></PRE
  14489. ></TD
  14490. ></TR
  14491. ></TABLE
  14492. ><P
  14493. ></P
  14494. ></DIV
  14495. >
  14496.      </P
  14497. ></DIV
  14498. ><DIV
  14499. CLASS="sect2"
  14500. ><HR><H3
  14501. CLASS="sect2"
  14502. ><A
  14503. NAME="language.types.integer.casting"
  14504. >Converting to integer</A
  14505. ></H3
  14506. ><P
  14507. >        To explicitly convert a value to <A
  14508. HREF="#language.types.integer"
  14509. ><B
  14510. CLASS="type"
  14511. >integer</B
  14512. ></A
  14513. >, use either
  14514.        the <VAR
  14515. CLASS="literal"
  14516. >(int)</VAR
  14517. > or the <VAR
  14518. CLASS="literal"
  14519. >(integer)</VAR
  14520. > cast.
  14521.        However, in most cases you do not need to use the cast, since a value
  14522.        will be automatically converted if an operator, function or 
  14523.        control structure requires an <A
  14524. HREF="#language.types.integer"
  14525. ><B
  14526. CLASS="type"
  14527. >integer</B
  14528. ></A
  14529. > argument.
  14530.        You can also convert a value to integer with the function
  14531.        <A
  14532. HREF="#function.intval"
  14533. ><B
  14534. CLASS="function"
  14535. >intval()</B
  14536. ></A
  14537. >.
  14538.       </P
  14539. ><P
  14540. >        See also <A
  14541. HREF="#language.types.type-juggling"
  14542. >type-juggling</A
  14543. >.
  14544.       </P
  14545. ><DIV
  14546. CLASS="sect3"
  14547. ><HR><H4
  14548. CLASS="sect3"
  14549. ><A
  14550. NAME="language.types.integer.casting.from-boolean"
  14551. >From <A
  14552. HREF="#language.types.boolean"
  14553. >booleans</A
  14554. ></A
  14555. ></H4
  14556. ><P
  14557. >         <TT
  14558. CLASS="constant"
  14559. ><B
  14560. >FALSE</B
  14561. ></TT
  14562. > will yield 
  14563.         <VAR
  14564. CLASS="literal"
  14565. >0</VAR
  14566. > (zero), and <TT
  14567. CLASS="constant"
  14568. ><B
  14569. >TRUE</B
  14570. ></TT
  14571. > 
  14572.         will yield <VAR
  14573. CLASS="literal"
  14574. >1</VAR
  14575. > (one).
  14576.        </P
  14577. ></DIV
  14578. ><DIV
  14579. CLASS="sect3"
  14580. ><HR><H4
  14581. CLASS="sect3"
  14582. ><A
  14583. NAME="language.types.integer.casting.from-float"
  14584. >From <A
  14585. HREF="#language.types.float"
  14586. >floating point numbers</A
  14587. ></A
  14588. ></H4
  14589. ><P
  14590. >         When converting from float to integer, the number will
  14591.         be rounded <SPAN
  14592. CLASS="emphasis"
  14593. ><I
  14594. CLASS="emphasis"
  14595. >towards zero</I
  14596. ></SPAN
  14597. >.
  14598.        </P
  14599. ><P
  14600. >         If the float is beyond the boundaries of integer
  14601.         (usually <VAR
  14602. CLASS="literal"
  14603. >+/- 2.15e+9 = 2^31</VAR
  14604. >), 
  14605.         the result is undefined, since the float hasn't
  14606.         got enough precision to give an exact integer result.
  14607.         No warning, not even a notice will be issued in this 
  14608.         case!
  14609.        </P
  14610. ><DIV
  14611. CLASS="warning"
  14612. ><P
  14613. ></P
  14614. ><TABLE
  14615. CLASS="warning"
  14616. BORDER="1"
  14617. WIDTH="100%"
  14618. ><TR
  14619. ><TD
  14620. ALIGN="CENTER"
  14621. ><B
  14622. >Warning</B
  14623. ></TD
  14624. ></TR
  14625. ><TR
  14626. ><TD
  14627. ALIGN="LEFT"
  14628. ><P
  14629. >         Never cast an unknown fraction to <A
  14630. HREF="#language.types.integer"
  14631. ><B
  14632. CLASS="type"
  14633. >integer</B
  14634. ></A
  14635. >, as this can
  14636.         sometimes lead to unexpected results.
  14637.         <DIV
  14638. CLASS="informalexample"
  14639. ><P
  14640. ></P
  14641. ><A
  14642. NAME="AEN2747"
  14643. ></A
  14644. ><TABLE
  14645. BORDER="0"
  14646. BGCOLOR="#E0E0E0"
  14647. CELLPADDING="5"
  14648. ><TR
  14649. ><TD
  14650. ><PRE
  14651. CLASS="php"
  14652. ><?php
  14653. echo (int) ( (0.1+0.7) * 10 ); // echoes 7!
  14654. ?></PRE
  14655. ></TD
  14656. ></TR
  14657. ></TABLE
  14658. ><P
  14659. ></P
  14660. ></DIV
  14661. >
  14662.         
  14663.         See for more information the <A
  14664. HREF="#warn.float-precision"
  14665. >warning 
  14666.         about float-precision</A
  14667. >.
  14668.        </P
  14669. ></TD
  14670. ></TR
  14671. ></TABLE
  14672. ></DIV
  14673. ></DIV
  14674. ><DIV
  14675. CLASS="sect3"
  14676. ><HR><H4
  14677. CLASS="sect3"
  14678. ><A
  14679. NAME="language.types.integer.casting.from-string"
  14680. >From strings</A
  14681. ></H4
  14682. ><P
  14683. >         See <A
  14684. HREF="#language.types.string.conversion"
  14685. >String 
  14686.         conversion to numbers</A
  14687. >
  14688.        </P
  14689. ></DIV
  14690. ><DIV
  14691. CLASS="sect3"
  14692. ><HR><H4
  14693. CLASS="sect3"
  14694. ><A
  14695. NAME="language.types.integer.casting.from-other"
  14696. >From other types</A
  14697. ></H4
  14698. ><P
  14699. >         <DIV
  14700. CLASS="caution"
  14701. ><P
  14702. ></P
  14703. ><TABLE
  14704. CLASS="caution"
  14705. BORDER="1"
  14706. WIDTH="100%"
  14707. ><TR
  14708. ><TD
  14709. ALIGN="CENTER"
  14710. ><B
  14711. >Caution</B
  14712. ></TD
  14713. ></TR
  14714. ><TR
  14715. ><TD
  14716. ALIGN="LEFT"
  14717. ><P
  14718. >           Behaviour of converting to integer is undefined for other
  14719.           types. Currently, the behaviour is the same as if the value
  14720.           was first <A
  14721. HREF="#language.types.boolean.casting"
  14722. >converted to boolean</A
  14723. >. However, do
  14724.           <SPAN
  14725. CLASS="emphasis"
  14726. ><I
  14727. CLASS="emphasis"
  14728. >not</I
  14729. ></SPAN
  14730. > rely on this behaviour, as it can
  14731.           change without notice.
  14732.          </P
  14733. ></TD
  14734. ></TR
  14735. ></TABLE
  14736. ></DIV
  14737. >
  14738.        </P
  14739. ></DIV
  14740. ></DIV
  14741. ></DIV
  14742. ><DIV
  14743. CLASS="sect1"
  14744. ><HR><H2
  14745. CLASS="sect1"
  14746. ><A
  14747. NAME="language.types.float"
  14748. >Floating point numbers</A
  14749. ></H2
  14750. ><P
  14751. >     Floating point numbers (AKA "floats", "doubles" or "real numbers") can be 
  14752.     specified using any of the following syntaxes: 
  14753.     <DIV
  14754. CLASS="informalexample"
  14755. ><P
  14756. ></P
  14757. ><A
  14758. NAME="AEN2764"
  14759. ></A
  14760. ><TABLE
  14761. BORDER="0"
  14762. BGCOLOR="#E0E0E0"
  14763. CELLPADDING="5"
  14764. ><TR
  14765. ><TD
  14766. ><PRE
  14767. CLASS="php"
  14768. ><?php
  14769. $a = 1.234; 
  14770. $b = 1.2e3; 
  14771. $c = 7E-10;
  14772. ?></PRE
  14773. ></TD
  14774. ></TR
  14775. ></TABLE
  14776. ><P
  14777. ></P
  14778. ></DIV
  14779. >
  14780.     Formally:
  14781.     <DIV
  14782. CLASS="informalexample"
  14783. ><P
  14784. ></P
  14785. ><A
  14786. NAME="AEN2766"
  14787. ></A
  14788. ><TABLE
  14789. BORDER="0"
  14790. BGCOLOR="#E0E0E0"
  14791. CELLPADDING="5"
  14792. ><TR
  14793. ><TD
  14794. ><PRE
  14795. CLASS="programlisting"
  14796. >LNUM          [0-9]+
  14797. DNUM          ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
  14798. EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})</PRE
  14799. ></TD
  14800. ></TR
  14801. ></TABLE
  14802. ><P
  14803. ></P
  14804. ></DIV
  14805. >
  14806.     The size of a float is platform-dependent, 
  14807.     although a maximum of ~1.8e308 with a precision of roughly 14 
  14808.     decimal digits is a common value (that's 64 bit IEEE format).
  14809.    </P
  14810. ><DIV
  14811. CLASS="warning"
  14812. ><P
  14813. ></P
  14814. ><TABLE
  14815. CLASS="warning"
  14816. BORDER="1"
  14817. WIDTH="100%"
  14818. ><TR
  14819. ><TD
  14820. ALIGN="CENTER"
  14821. ><B
  14822. ><A
  14823. NAME="warn.float-precision"
  14824. ></A
  14825. >Floating point precision</B
  14826. ></TD
  14827. ></TR
  14828. ><TR
  14829. ><TD
  14830. ALIGN="LEFT"
  14831. ><P
  14832. >      It is quite usual that simple decimal fractions like
  14833.      <VAR
  14834. CLASS="literal"
  14835. >0.1</VAR
  14836. > or <VAR
  14837. CLASS="literal"
  14838. >0.7</VAR
  14839. > cannot be
  14840.      converted into their internal binary counterparts without a
  14841.      little loss of precision. This can lead to confusing results: for
  14842.      example, <VAR
  14843. CLASS="literal"
  14844. >floor((0.1+0.7)*10)</VAR
  14845. > will usually
  14846.      return <VAR
  14847. CLASS="literal"
  14848. >7</VAR
  14849. > instead of the expected
  14850.      <VAR
  14851. CLASS="literal"
  14852. >8</VAR
  14853. > as the result of the internal representation
  14854.      really being something like <VAR
  14855. CLASS="literal"
  14856. >7.9999999999...</VAR
  14857. >.
  14858.     </P
  14859. ><P
  14860. >      This is related to the fact that it is impossible to exactly
  14861.      express some fractions in decimal notation with a finite number
  14862.      of digits. For instance, <VAR
  14863. CLASS="literal"
  14864. >1/3</VAR
  14865. > in decimal form
  14866.      becomes <VAR
  14867. CLASS="literal"
  14868. >0.3333333. . .</VAR
  14869. >.
  14870.     </P
  14871. ><P
  14872. >      So never trust floating number results to the last digit and
  14873.      never compare floating point numbers for equality. If you really
  14874.      need higher precision, you should use the <A
  14875. HREF="#ref.bc"
  14876. >arbitrary precision math functions</A
  14877. >
  14878.      or <A
  14879. HREF="#ref.gmp"
  14880. >gmp</A
  14881. > functions instead.
  14882.     </P
  14883. ></TD
  14884. ></TR
  14885. ></TABLE
  14886. ></DIV
  14887. ><DIV
  14888. CLASS="sect2"
  14889. ><HR><H3
  14890. CLASS="sect2"
  14891. ><A
  14892. NAME="language.types.float.casting"
  14893. >Converting to float</A
  14894. ></H3
  14895. ><P
  14896. >      For information on when and how strings are converted to floats,
  14897.      see the section titled <A
  14898. HREF="#language.types.string.conversion"
  14899. >String
  14900.      conversion to numbers</A
  14901. >. For values of other types, the conversion
  14902.      is the same as if the value would have been converted to integer
  14903.      and then to float. See the <A
  14904. HREF="#language.types.integer.casting"
  14905. >Converting
  14906.      to integer</A
  14907. > section for more information.
  14908.      As of PHP 5, notice is thrown if you try to convert object to float.
  14909.     </P
  14910. ></DIV
  14911. ></DIV
  14912. ><DIV
  14913. CLASS="sect1"
  14914. ><HR><H2
  14915. CLASS="sect1"
  14916. ><A
  14917. NAME="language.types.string"
  14918. >Strings</A
  14919. ></H2
  14920. ><P
  14921. >     A <A
  14922. HREF="#language.types.string"
  14923. ><B
  14924. CLASS="type"
  14925. >string</B
  14926. ></A
  14927. > is series of characters. In PHP,
  14928.     a character is the same as a byte, that is, there are exactly
  14929.     256 different characters possible. This also implies that PHP
  14930.     has no native support of Unicode. See <A
  14931. HREF="#function.utf8-encode"
  14932. ><B
  14933. CLASS="function"
  14934. >utf8_encode()</B
  14935. ></A
  14936. >
  14937.     and <A
  14938. HREF="#function.utf8-decode"
  14939. ><B
  14940. CLASS="function"
  14941. >utf8_decode()</B
  14942. ></A
  14943. > for some Unicode support.
  14944.    </P
  14945. ><DIV
  14946. CLASS="note"
  14947. ><BLOCKQUOTE
  14948. CLASS="note"
  14949. ><P
  14950. ><B
  14951. >Note: </B
  14952. >
  14953.      It is no problem for a string to become very large. 
  14954.      There is no practical bound to the size
  14955.      of strings imposed by PHP, so there is no reason at all
  14956.      to worry about long strings.
  14957.     </P
  14958. ></BLOCKQUOTE
  14959. ></DIV
  14960. ><DIV
  14961. CLASS="sect2"
  14962. ><HR><H3
  14963. CLASS="sect2"
  14964. ><A
  14965. NAME="language.types.string.syntax"
  14966. >Syntax</A
  14967. ></H3
  14968. ><P
  14969. >      A string literal can be specified in three different
  14970.      ways.
  14971.      <P
  14972. ></P
  14973. ><UL
  14974. ><LI
  14975. ><P
  14976. >         <A
  14977. HREF="#language.types.string.syntax.single"
  14978. >single quoted</A
  14979. >
  14980.        </P
  14981. ></LI
  14982. ><LI
  14983. ><P
  14984. >         <A
  14985. HREF="#language.types.string.syntax.double"
  14986. >double quoted</A
  14987. >
  14988.        </P
  14989. ></LI
  14990. ><LI
  14991. ><P
  14992. >         <A
  14993. HREF="#language.types.string.syntax.heredoc"
  14994. >heredoc syntax</A
  14995. >
  14996.        </P
  14997. ></LI
  14998. ></UL
  14999. >
  15000.     </P
  15001. ><DIV
  15002. CLASS="sect3"
  15003. ><HR><H4
  15004. CLASS="sect3"
  15005. ><A
  15006. NAME="language.types.string.syntax.single"
  15007. >Single quoted</A
  15008. ></H4
  15009. ><P
  15010. >       The easiest way to specify a simple string is to
  15011.       enclose it in single quotes (the character <VAR
  15012. CLASS="literal"
  15013. >'</VAR
  15014. >). 
  15015.      </P
  15016. ><P
  15017. >       To specify a literal single
  15018.       quote, you will need to escape it with a backslash
  15019.       (<VAR
  15020. CLASS="literal"
  15021. >\</VAR
  15022. >), like in many other languages.
  15023.       If a backslash needs to occur before a single quote or at 
  15024.       the end of the string, you need to double it.
  15025.       Note that if you try to escape any
  15026.       other character, the backslash will also be printed! So
  15027.       usually there is no need to escape the backslash itself.
  15028.       <DIV
  15029. CLASS="note"
  15030. ><BLOCKQUOTE
  15031. CLASS="note"
  15032. ><P
  15033. ><B
  15034. >Note: </B
  15035. >
  15036.         In PHP 3, a warning will
  15037.         be issued at the <VAR
  15038. CLASS="literal"
  15039. >E_NOTICE</VAR
  15040. > level when this
  15041.         happens.
  15042.        </P
  15043. ></BLOCKQUOTE
  15044. ></DIV
  15045. >
  15046.       <DIV
  15047. CLASS="note"
  15048. ><BLOCKQUOTE
  15049. CLASS="note"
  15050. ><P
  15051. ><B
  15052. >Note: </B
  15053. >
  15054.         Unlike the two other syntaxes, <A
  15055. HREF="#language.variables"
  15056. >variables</A
  15057. > and escape sequences
  15058.         for special characters will <SPAN
  15059. CLASS="emphasis"
  15060. ><I
  15061. CLASS="emphasis"
  15062. >not</I
  15063. ></SPAN
  15064. > be expanded 
  15065.         when they occur in single quoted strings.
  15066.        </P
  15067. ></BLOCKQUOTE
  15068. ></DIV
  15069. >
  15070.       <DIV
  15071. CLASS="informalexample"
  15072. ><P
  15073. ></P
  15074. ><A
  15075. NAME="AEN2822"
  15076. ></A
  15077. ><TABLE
  15078. BORDER="0"
  15079. BGCOLOR="#E0E0E0"
  15080. CELLPADDING="5"
  15081. ><TR
  15082. ><TD
  15083. ><PRE
  15084. CLASS="php"
  15085. ><?php
  15086. echo 'this is a simple string';
  15087.  
  15088. echo 'You can also have embedded newlines in 
  15089. strings this way as it is
  15090. okay to do';
  15091.  
  15092. // Outputs: Arnold once said: "I'll be back"
  15093. echo 'Arnold once said: "I\'ll be back"';
  15094.  
  15095. // Outputs: You deleted C:\*.*?
  15096. echo 'You deleted C:\\*.*?';
  15097.  
  15098. // Outputs: You deleted C:\*.*?
  15099. echo 'You deleted C:\*.*?';
  15100.  
  15101. // Outputs: This will not expand: \n a newline
  15102. echo 'This will not expand: \n a newline';
  15103.  
  15104. // Outputs: Variables do not $expand $either
  15105. echo 'Variables do not $expand $either';
  15106. ?></PRE
  15107. ></TD
  15108. ></TR
  15109. ></TABLE
  15110. ><P
  15111. ></P
  15112. ></DIV
  15113. >
  15114.      </P
  15115. ></DIV
  15116. ><DIV
  15117. CLASS="sect3"
  15118. ><HR><H4
  15119. CLASS="sect3"
  15120. ><A
  15121. NAME="language.types.string.syntax.double"
  15122. >Double quoted</A
  15123. ></H4
  15124. ><P
  15125. >       If the string is enclosed in double-quotes ("),
  15126.       PHP understands more escape sequences for special
  15127.       characters:
  15128.      </P
  15129. ><DIV
  15130. CLASS="table"
  15131. ><A
  15132. NAME="AEN2827"
  15133. ></A
  15134. ><P
  15135. ><B
  15136. >Table 11-1. Escaped characters</B
  15137. ></P
  15138. ><TABLE
  15139. BORDER="1"
  15140. CLASS="CALSTABLE"
  15141. ><COL><COL><THEAD
  15142. ><TR
  15143. ><TH
  15144. >sequence</TH
  15145. ><TH
  15146. >meaning</TH
  15147. ></TR
  15148. ></THEAD
  15149. ><TBODY
  15150. ><TR
  15151. ><TD
  15152. ><VAR
  15153. CLASS="literal"
  15154. >\n</VAR
  15155. ></TD
  15156. ><TD
  15157. >linefeed (LF or 0x0A (10) in ASCII)</TD
  15158. ></TR
  15159. ><TR
  15160. ><TD
  15161. ><VAR
  15162. CLASS="literal"
  15163. >\r</VAR
  15164. ></TD
  15165. ><TD
  15166. >carriage return (CR or 0x0D (13) in ASCII)</TD
  15167. ></TR
  15168. ><TR
  15169. ><TD
  15170. ><VAR
  15171. CLASS="literal"
  15172. >\t</VAR
  15173. ></TD
  15174. ><TD
  15175. >horizontal tab (HT or 0x09 (9) in ASCII)</TD
  15176. ></TR
  15177. ><TR
  15178. ><TD
  15179. ><VAR
  15180. CLASS="literal"
  15181. >\\</VAR
  15182. ></TD
  15183. ><TD
  15184. >backslash</TD
  15185. ></TR
  15186. ><TR
  15187. ><TD
  15188. ><VAR
  15189. CLASS="literal"
  15190. >\$</VAR
  15191. ></TD
  15192. ><TD
  15193. >dollar sign</TD
  15194. ></TR
  15195. ><TR
  15196. ><TD
  15197. ><VAR
  15198. CLASS="literal"
  15199. >\"</VAR
  15200. ></TD
  15201. ><TD
  15202. >double-quote</TD
  15203. ></TR
  15204. ><TR
  15205. ><TD
  15206. ><VAR
  15207. CLASS="literal"
  15208. >\[0-7]{1,3}</VAR
  15209. ></TD
  15210. ><TD
  15211. >           the sequence of characters matching the regular
  15212.           expression is a character in octal notation
  15213.          </TD
  15214. ></TR
  15215. ><TR
  15216. ><TD
  15217. ><VAR
  15218. CLASS="literal"
  15219. >\x[0-9A-Fa-f]{1,2}</VAR
  15220. ></TD
  15221. ><TD
  15222. >           the sequence of characters matching the regular
  15223.           expression is a character in hexadecimal notation
  15224.          </TD
  15225. ></TR
  15226. ></TBODY
  15227. ></TABLE
  15228. ></DIV
  15229. ><P
  15230. >       Again, if you try to escape any other character, the
  15231.       backslash will be printed too!
  15232.      </P
  15233. ><P
  15234. >       But the most important feature of double-quoted strings
  15235.       is the fact that variable names will be expanded.
  15236.       See <A
  15237. HREF="#language.types.string.parsing"
  15238. >string 
  15239.       parsing</A
  15240. > for details.
  15241.      </P
  15242. ></DIV
  15243. ><DIV
  15244. CLASS="sect3"
  15245. ><HR><H4
  15246. CLASS="sect3"
  15247. ><A
  15248. NAME="language.types.string.syntax.heredoc"
  15249. >Heredoc</A
  15250. ></H4
  15251. ><P
  15252. >       Another way to delimit strings is by using heredoc syntax
  15253.       ("<<<").  One should provide an identifier after
  15254.       <VAR
  15255. CLASS="literal"
  15256. ><<<</VAR
  15257. >, then the string, and then the
  15258.       same identifier to close the quotation. 
  15259.      </P
  15260. ><P
  15261. >       The closing identifier <SPAN
  15262. CLASS="emphasis"
  15263. ><I
  15264. CLASS="emphasis"
  15265. >must</I
  15266. ></SPAN
  15267. > begin in the
  15268.       first column of the line. Also, the identifier used must follow
  15269.       the same naming rules as any other label in PHP: it must contain
  15270.       only alphanumeric characters and underscores, and must start with
  15271.       a non-digit character or underscore.
  15272.      </P
  15273. ><DIV
  15274. CLASS="warning"
  15275. ><P
  15276. ></P
  15277. ><TABLE
  15278. CLASS="warning"
  15279. BORDER="1"
  15280. WIDTH="100%"
  15281. ><TR
  15282. ><TD
  15283. ALIGN="CENTER"
  15284. ><B
  15285. >Warning</B
  15286. ></TD
  15287. ></TR
  15288. ><TR
  15289. ><TD
  15290. ALIGN="LEFT"
  15291. ><P
  15292. >        It is very important to note that the line with the closing
  15293.        identifier contains no other characters, except 
  15294.        <SPAN
  15295. CLASS="emphasis"
  15296. ><I
  15297. CLASS="emphasis"
  15298. >possibly</I
  15299. ></SPAN
  15300. > a semicolon (<VAR
  15301. CLASS="literal"
  15302. >;</VAR
  15303. >).
  15304.        That means especially that the identifier 
  15305.        <SPAN
  15306. CLASS="emphasis"
  15307. ><I
  15308. CLASS="emphasis"
  15309. >may not be indented</I
  15310. ></SPAN
  15311. >, and there
  15312.        may not be any spaces or tabs after or before the semicolon.
  15313.        It's also important to realize that the first character before
  15314.        the closing identifier must be a newline as defined by your
  15315.        operating system. This is <VAR
  15316. CLASS="literal"
  15317. >\r</VAR
  15318. > on Macintosh
  15319.        for example.
  15320.       </P
  15321. ><P
  15322. >        If this rule is broken and the closing identifier is not "clean"
  15323.        then it's not considered to be a closing identifier and PHP 
  15324.        will continue looking for one.  If in this case a proper closing 
  15325.        identifier is not found then a parse error will result with the 
  15326.        line number being at the end of the script.
  15327.       </P
  15328. ></TD
  15329. ></TR
  15330. ></TABLE
  15331. ></DIV
  15332. ><P
  15333. >       Heredoc text behaves just like a double-quoted string, without
  15334.       the double-quotes. This means that you do not need to escape quotes
  15335.       in your here docs, but you can still use the escape codes listed
  15336.       above. Variables are expanded, but the same care must be taken
  15337.       when expressing complex variables inside a here doc as with
  15338.       strings.
  15339.       <TABLE
  15340. WIDTH="100%"
  15341. BORDER="0"
  15342. CELLPADDING="0"
  15343. CELLSPACING="0"
  15344. CLASS="EXAMPLE"
  15345. ><TR
  15346. ><TD
  15347. ><DIV
  15348. CLASS="example"
  15349. ><A
  15350. NAME="AEN2884"
  15351. ></A
  15352. ><P
  15353. ><B
  15354. >Example 11-3. Heredoc string quoting example</B
  15355. ></P
  15356. ><TABLE
  15357. BORDER="0"
  15358. BGCOLOR="#E0E0E0"
  15359. CELLPADDING="5"
  15360. ><TR
  15361. ><TD
  15362. ><PRE
  15363. CLASS="php"
  15364. ><?php
  15365. $str = <<<EOD
  15366. Example of string
  15367. spanning multiple lines
  15368. using heredoc syntax.
  15369. EOD;
  15370.  
  15371. /* More complex example, with variables. */
  15372. class foo
  15373. {
  15374.     var $foo;
  15375.     var $bar;
  15376.  
  15377.     function foo()
  15378.     {
  15379.         $this->foo = 'Foo';
  15380.         $this->bar = array('Bar1', 'Bar2', 'Bar3');
  15381.     }
  15382. }
  15383.  
  15384. $foo = new foo();
  15385. $name = 'MyName';
  15386.  
  15387. echo <<<EOT
  15388. My name is "$name". I am printing some $foo->foo.
  15389. Now, I am printing some {$foo->bar[1]}.
  15390. This should print a capital 'A': \x41
  15391. EOT;
  15392. ?></PRE
  15393. ></TD
  15394. ></TR
  15395. ></TABLE
  15396. ></DIV
  15397. ></TD
  15398. ></TR
  15399. ></TABLE
  15400. >
  15401.      </P
  15402. ><DIV
  15403. CLASS="note"
  15404. ><BLOCKQUOTE
  15405. CLASS="note"
  15406. ><P
  15407. ><B
  15408. >Note: </B
  15409. >
  15410.        Heredoc support was added in PHP 4.
  15411.       </P
  15412. ></BLOCKQUOTE
  15413. ></DIV
  15414. ></DIV
  15415. ><DIV
  15416. CLASS="sect3"
  15417. ><HR><H4
  15418. CLASS="sect3"
  15419. ><A
  15420. NAME="language.types.string.parsing"
  15421. >Variable parsing</A
  15422. ></H4
  15423. ><P
  15424. >       When a string is specified in double quotes or with
  15425.       heredoc, <A
  15426. HREF="#language.variables"
  15427. >variables</A
  15428. > are 
  15429.       parsed within it. 
  15430.      </P
  15431. ><P
  15432. >       There are two types of syntax: a 
  15433.       <A
  15434. HREF="#language.types.string.parsing.simple"
  15435. >simple</A
  15436. >
  15437.       one and a 
  15438.       <A
  15439. HREF="#language.types.string.parsing.complex"
  15440. >complex</A
  15441. >
  15442.       one.
  15443.       The simple syntax is the most common and convenient. It provides a way
  15444.       to parse a variable, an <A
  15445. HREF="#language.types.array"
  15446. ><B
  15447. CLASS="type"
  15448. >array</B
  15449. ></A
  15450. > value, or an 
  15451.       object property.
  15452.      </P
  15453. ><P
  15454. >       The complex syntax was introduced in PHP 4, and can be recognised
  15455.       by the curly braces surrounding the expression.
  15456.      </P
  15457. ><DIV
  15458. CLASS="sect4"
  15459. ><HR><H5
  15460. CLASS="sect4"
  15461. ><A
  15462. NAME="language.types.string.parsing.simple"
  15463. >Simple syntax</A
  15464. ></H5
  15465. ><P
  15466. >        If a dollar sign (<VAR
  15467. CLASS="literal"
  15468. >$</VAR
  15469. >) is encountered, the
  15470.        parser will greedily take as many tokens as possible to form a
  15471.        valid variable name. Enclose the variable name in curly
  15472.        braces if you want to explicitly specify the end of the name.
  15473.       </P
  15474. ><DIV
  15475. CLASS="informalexample"
  15476. ><P
  15477. ></P
  15478. ><A
  15479. NAME="AEN2903"
  15480. ></A
  15481. ><TABLE
  15482. BORDER="0"
  15483. BGCOLOR="#E0E0E0"
  15484. CELLPADDING="5"
  15485. ><TR
  15486. ><TD
  15487. ><PRE
  15488. CLASS="php"
  15489. ><?php
  15490. $beer = 'Heineken';
  15491. echo "$beer's taste is great"; // works, "'" is an invalid character for varnames
  15492. echo "He drank some $beers";   // won't work, 's' is a valid character for varnames
  15493. echo "He drank some ${beer}s"; // works
  15494. echo "He drank some {$beer}s"; // works
  15495. ?></PRE
  15496. ></TD
  15497. ></TR
  15498. ></TABLE
  15499. ><P
  15500. ></P
  15501. ></DIV
  15502. ><P
  15503. >        Similarly, you can also have an <A
  15504. HREF="#language.types.array"
  15505. ><B
  15506. CLASS="type"
  15507. >array</B
  15508. ></A
  15509. > index or an 
  15510.        object property parsed. With array indices, the closing square 
  15511.        bracket (<VAR
  15512. CLASS="literal"
  15513. >]</VAR
  15514. >) marks the end of the index. For
  15515.        object properties the same rules apply as to simple variables,
  15516.        though with object properties there doesn't exist a trick like
  15517.        the one with variables.
  15518.        
  15519.        
  15520.       
  15521.       </P
  15522. ><DIV
  15523. CLASS="informalexample"
  15524. ><P
  15525. ></P
  15526. ><A
  15527. NAME="AEN2909"
  15528. ></A
  15529. ><TABLE
  15530. BORDER="0"
  15531. BGCOLOR="#E0E0E0"
  15532. CELLPADDING="5"
  15533. ><TR
  15534. ><TD
  15535. ><PRE
  15536. CLASS="php"
  15537. ><?php
  15538. // These examples are specific to using arrays inside of strings.
  15539. // When outside of a string, always quote your array string keys 
  15540. // and do not use {braces} when outside of strings either.
  15541.  
  15542. // Let's show all errors
  15543. error_reporting(E_ALL);
  15544.  
  15545. $fruits = array('strawberry' => 'red', 'banana' => 'yellow');
  15546.  
  15547. // Works but note that this works differently outside string-quotes
  15548. echo "A banana is $fruits[banana].";
  15549.  
  15550. // Works
  15551. echo "A banana is {$fruits['banana']}.";
  15552.  
  15553. // Works but PHP looks for a constant named banana first
  15554. // as described below.
  15555. echo "A banana is {$fruits[banana]}.";
  15556.  
  15557. // Won't work, use braces.  This results in a parse error.
  15558. echo "A banana is $fruits['banana'].";
  15559.  
  15560. // Works
  15561. echo "A banana is " . $fruits['banana'] . ".";
  15562.  
  15563. // Works
  15564. echo "This square is $square->width meters broad.";
  15565.  
  15566. // Won't work. For a solution, see the complex syntax.
  15567. echo "This square is $square->width00 centimeters broad.";
  15568. ?></PRE
  15569. ></TD
  15570. ></TR
  15571. ></TABLE
  15572. ><P
  15573. ></P
  15574. ></DIV
  15575. ><P
  15576. >        For anything more complex, you should use the complex syntax.
  15577.       </P
  15578. ></DIV
  15579. ><DIV
  15580. CLASS="sect4"
  15581. ><HR><H5
  15582. CLASS="sect4"
  15583. ><A
  15584. NAME="language.types.string.parsing.complex"
  15585. >Complex (curly) syntax</A
  15586. ></H5
  15587. ><P
  15588. >        This isn't called complex because the syntax is complex,
  15589.        but because you can include complex expressions this way.
  15590.      </P
  15591. ><P
  15592. >       In fact, you can include any value that is in the namespace
  15593.       in strings with this syntax. You simply write the expression
  15594.       the same way as you would outside the string, and then include
  15595.       it in { and }. Since you can't escape '{', this syntax will
  15596.       only be recognised when the $ is immediately following the {.
  15597.       (Use "{\$" or "\{$" to get a literal "{$").
  15598.       Some examples to make it clear:
  15599.      </P
  15600. ><DIV
  15601. CLASS="informalexample"
  15602. ><P
  15603. ></P
  15604. ><A
  15605. NAME="AEN2916"
  15606. ></A
  15607. ><TABLE
  15608. BORDER="0"
  15609. BGCOLOR="#E0E0E0"
  15610. CELLPADDING="5"
  15611. ><TR
  15612. ><TD
  15613. ><PRE
  15614. CLASS="php"
  15615. ><?php
  15616. // Let's show all errors
  15617. error_reporting(E_ALL);
  15618.  
  15619. $great = 'fantastic';
  15620.  
  15621. // Won't work, outputs: This is { fantastic}
  15622. echo "This is { $great}";
  15623.  
  15624. // Works, outputs: This is fantastic
  15625. echo "This is {$great}";
  15626. echo "This is ${great}";
  15627.  
  15628. // Works
  15629. echo "This square is {$square->width}00 centimeters broad."; 
  15630.  
  15631. // Works
  15632. echo "This works: {$arr[4][3]}";
  15633.  
  15634. // This is wrong for the same reason as $foo[bar] is wrong 
  15635. // outside a string.  In other words, it will still work but
  15636. // because PHP first looks for a constant named foo, it will
  15637. // throw an error of level E_NOTICE (undefined constant).
  15638. echo "This is wrong: {$arr[foo][3]}"; 
  15639.  
  15640. // Works.  When using multi-dimensional arrays, always use
  15641. // braces around arrays when inside of strings
  15642. echo "This works: {$arr['foo'][3]}";
  15643.  
  15644. // Works.
  15645. echo "This works: " . $arr['foo'][3];
  15646.  
  15647. echo "You can even write {$obj->values[3]->name}";
  15648.  
  15649. echo "This is the value of the var named $name: {${$name}}";
  15650. ?></PRE
  15651. ></TD
  15652. ></TR
  15653. ></TABLE
  15654. ><P
  15655. ></P
  15656. ></DIV
  15657. ></DIV
  15658. ></DIV
  15659. ><DIV
  15660. CLASS="sect3"
  15661. ><HR><H4
  15662. CLASS="sect3"
  15663. ><A
  15664. NAME="language.types.string.substr"
  15665. >String access and modification by character</A
  15666. ></H4
  15667. ><P
  15668. >       Characters within strings may be accessed and modified by specifying the
  15669.       zero-based offset of the desired character after the string 
  15670.       in curly braces.
  15671.      </P
  15672. ><DIV
  15673. CLASS="note"
  15674. ><BLOCKQUOTE
  15675. CLASS="note"
  15676. ><P
  15677. ><B
  15678. >Note: </B
  15679. >
  15680.        For backwards compatibility, you can still use array-brackets
  15681.        for the same purpose. However, this syntax is deprecated as
  15682.        of PHP 4.
  15683.       </P
  15684. ></BLOCKQUOTE
  15685. ></DIV
  15686. ><P
  15687. >       <TABLE
  15688. WIDTH="100%"
  15689. BORDER="0"
  15690. CELLPADDING="0"
  15691. CELLSPACING="0"
  15692. CLASS="EXAMPLE"
  15693. ><TR
  15694. ><TD
  15695. ><DIV
  15696. CLASS="example"
  15697. ><A
  15698. NAME="AEN2924"
  15699. ></A
  15700. ><P
  15701. ><B
  15702. >Example 11-4. Some string examples</B
  15703. ></P
  15704. ><TABLE
  15705. BORDER="0"
  15706. BGCOLOR="#E0E0E0"
  15707. CELLPADDING="5"
  15708. ><TR
  15709. ><TD
  15710. ><PRE
  15711. CLASS="php"
  15712. ><?php
  15713. // Get the first character of a string
  15714. $str = 'This is a test.';
  15715. $first = $str{0};
  15716.  
  15717. // Get the third character of a string
  15718. $third = $str{2};
  15719.  
  15720. // Get the last character of a string.
  15721. $str = 'This is still a test.';
  15722. $last = $str{strlen($str)-1}; 
  15723.  
  15724. // Modify the last character of a string
  15725. $str = 'Look at the sea';
  15726. $str{strlen($str)-1} = 'e';
  15727.           
  15728. ?></PRE
  15729. ></TD
  15730. ></TR
  15731. ></TABLE
  15732. ></DIV
  15733. ></TD
  15734. ></TR
  15735. ></TABLE
  15736. >
  15737.      </P
  15738. ></DIV
  15739. ></DIV
  15740. ><DIV
  15741. CLASS="sect2"
  15742. ><HR><H3
  15743. CLASS="sect2"
  15744. ><A
  15745. NAME="language.types.string.useful-funcs"
  15746. >Useful functions and operators</A
  15747. ></H3
  15748. ><P
  15749. >      Strings may be concatenated using the '.' (dot) operator. Note
  15750.      that the '+' (addition) operator will not work for this. Please
  15751.      see <A
  15752. HREF="#language.operators.string"
  15753. >String
  15754.      operators</A
  15755. > for more information.
  15756.     </P
  15757. ><P
  15758. >      There are a lot of useful functions for string modification.
  15759.     </P
  15760. ><P
  15761. >      See the <A
  15762. HREF="#ref.strings"
  15763. >string functions section</A
  15764. > 
  15765.      for general functions, the regular expression functions for
  15766.      advanced find&replacing (in two tastes: 
  15767.      <A
  15768. HREF="#ref.pcre"
  15769. >Perl</A
  15770. > and 
  15771.      <A
  15772. HREF="#ref.regex"
  15773. >POSIX extended</A
  15774. >).
  15775.     </P
  15776. ><P
  15777. >      There are also <A
  15778. HREF="#ref.url"
  15779. >functions for URL-strings</A
  15780. >,
  15781.      and functions to encrypt/decrypt strings 
  15782.      (<A
  15783. HREF="#ref.mcrypt"
  15784. >mcrypt</A
  15785. > and 
  15786.      <A
  15787. HREF="#ref.mhash"
  15788. >mhash</A
  15789. >).
  15790.     </P
  15791. ><P
  15792. >      Finally, if you still didn't find what you're looking for,
  15793.      see also the <A
  15794. HREF="#ref.ctype"
  15795. >character type functions</A
  15796. >.
  15797.     </P
  15798. ></DIV
  15799. ><DIV
  15800. CLASS="sect2"
  15801. ><HR><H3
  15802. CLASS="sect2"
  15803. ><A
  15804. NAME="language.types.string.casting"
  15805. >Converting to string</A
  15806. ></H3
  15807. ><P
  15808. >      You can convert a value to a string using the <VAR
  15809. CLASS="literal"
  15810. >(string)</VAR
  15811. >
  15812.      cast, or the <A
  15813. HREF="#function.strval"
  15814. ><B
  15815. CLASS="function"
  15816. >strval()</B
  15817. ></A
  15818. > function. String conversion
  15819.      is automatically done in the scope of an expression for you where a
  15820.      string is needed. This happens when you use the <A
  15821. HREF="#function.echo"
  15822. ><B
  15823. CLASS="function"
  15824. >echo()</B
  15825. ></A
  15826. >
  15827.      or <A
  15828. HREF="#function.print"
  15829. ><B
  15830. CLASS="function"
  15831. >print()</B
  15832. ></A
  15833. > functions, or when you compare a variable
  15834.      value to a string.  Reading the manual sections on <A
  15835. HREF="#language.types"
  15836. >Types</A
  15837. > and <A
  15838. HREF="#language.types.type-juggling"
  15839. >Type Juggling</A
  15840. > will make
  15841.      the following clearer.  See also <A
  15842. HREF="#function.settype"
  15843. ><B
  15844. CLASS="function"
  15845. >settype()</B
  15846. ></A
  15847. >.
  15848.     </P
  15849. ><P
  15850. >      A <A
  15851. HREF="#language.types.boolean"
  15852. ><B
  15853. CLASS="type"
  15854. >boolean</B
  15855. ></A
  15856. > <TT
  15857. CLASS="constant"
  15858. ><B
  15859. >TRUE</B
  15860. ></TT
  15861. > value is converted to the string <VAR
  15862. CLASS="literal"
  15863. >"1"</VAR
  15864. >,
  15865.      the <TT
  15866. CLASS="constant"
  15867. ><B
  15868. >FALSE</B
  15869. ></TT
  15870. > value is represented as <VAR
  15871. CLASS="literal"
  15872. >""</VAR
  15873. > (empty string).
  15874.      This way you can convert back and forth between boolean and string values.
  15875.     </P
  15876. ><P
  15877. > 
  15878.      An <A
  15879. HREF="#language.types.integer"
  15880. ><B
  15881. CLASS="type"
  15882. >integer</B
  15883. ></A
  15884. > or a floating point number (<A
  15885. HREF="#language.types.float"
  15886. ><B
  15887. CLASS="type"
  15888. >float</B
  15889. ></A
  15890. >) 
  15891.      is converted to a string representing the number with its digits
  15892.      (including the exponent part for floating point numbers).
  15893.     </P
  15894. ><P
  15895. >      Arrays are always converted to the string <VAR
  15896. CLASS="literal"
  15897. >"Array"</VAR
  15898. >,
  15899.      so you cannot dump out the contents of an <A
  15900. HREF="#language.types.array"
  15901. ><B
  15902. CLASS="type"
  15903. >array</B
  15904. ></A
  15905. > with 
  15906.      <A
  15907. HREF="#function.echo"
  15908. ><B
  15909. CLASS="function"
  15910. >echo()</B
  15911. ></A
  15912. > or <A
  15913. HREF="#function.print"
  15914. ><B
  15915. CLASS="function"
  15916. >print()</B
  15917. ></A
  15918. > to see what is inside 
  15919.      them.  To view one element, you'd do something like <VAR
  15920. CLASS="literal"
  15921. >      echo $arr['foo']</VAR
  15922. >.  See below for tips on dumping/viewing the 
  15923.      entire contents.
  15924.     </P
  15925. ><P
  15926. >      Objects are always converted to the string <VAR
  15927. CLASS="literal"
  15928. >"Object"</VAR
  15929. >.
  15930.      If you would like to print out the member variable values of an 
  15931.      <A
  15932. HREF="#language.types.object"
  15933. ><B
  15934. CLASS="type"
  15935. >object</B
  15936. ></A
  15937. > for debugging reasons, read the paragraphs 
  15938.      below. If you would like to find out the class name of which an object 
  15939.      is an instance of, use <A
  15940. HREF="#function.get-class"
  15941. ><B
  15942. CLASS="function"
  15943. >get_class()</B
  15944. ></A
  15945. >.
  15946.      As of PHP 5, __toString() method is used if applicable.
  15947.     </P
  15948. ><P
  15949. >      Resources are always converted to strings with the structure
  15950.      <VAR
  15951. CLASS="literal"
  15952. >"Resource id #1"</VAR
  15953. > where <VAR
  15954. CLASS="literal"
  15955. >1</VAR
  15956. > is
  15957.      the unique number of the <A
  15958. HREF="#language.types.resource"
  15959. ><B
  15960. CLASS="type"
  15961. >resource</B
  15962. ></A
  15963. > assigned by PHP during runtime.
  15964.      If you would like to get the type of the resource, use
  15965.      <A
  15966. HREF="#function.get-resource-type"
  15967. ><B
  15968. CLASS="function"
  15969. >get_resource_type()</B
  15970. ></A
  15971. >.
  15972.     </P
  15973. ><P
  15974. >      <TT
  15975. CLASS="constant"
  15976. ><B
  15977. >NULL</B
  15978. ></TT
  15979. > is always converted to an empty string.
  15980.     </P
  15981. ><P
  15982. >      As you can see above, printing out the arrays, objects or resources does not
  15983.      provide you any useful information about the values themselves. Look at the
  15984.      functions <A
  15985. HREF="#function.print-r"
  15986. ><B
  15987. CLASS="function"
  15988. >print_r()</B
  15989. ></A
  15990. > and <A
  15991. HREF="#function.var-dump"
  15992. ><B
  15993. CLASS="function"
  15994. >var_dump()</B
  15995. ></A
  15996. >
  15997.      for better ways to print out values for debugging.
  15998.     </P
  15999. ><P
  16000. >      You can also convert PHP values to strings to store them permanently. This
  16001.      method is called serialization, and can be done with the function
  16002.      <A
  16003. HREF="#function.serialize"
  16004. ><B
  16005. CLASS="function"
  16006. >serialize()</B
  16007. ></A
  16008. >. You can also serialize PHP values to
  16009.      XML structures, if you have <A
  16010. HREF="#ref.wddx"
  16011. >WDDX</A
  16012. > support
  16013.      in your PHP setup.
  16014.     </P
  16015. ></DIV
  16016. ><DIV
  16017. CLASS="sect2"
  16018. ><HR><H3
  16019. CLASS="sect2"
  16020. ><A
  16021. NAME="language.types.string.conversion"
  16022. >String conversion to numbers</A
  16023. ></H3
  16024. ><P
  16025. >      When a string is evaluated as a numeric value, the resulting
  16026.      value and type are determined as follows.
  16027.     </P
  16028. ><P
  16029. >      The string will evaluate as a <A
  16030. HREF="#language.types.float"
  16031. ><B
  16032. CLASS="type"
  16033. >float</B
  16034. ></A
  16035. > if it contains any of the
  16036.      characters '.', 'e', or 'E'. Otherwise, it will evaluate as an
  16037.      integer.
  16038.     </P
  16039. ><P
  16040. >      The value is given by the initial portion of the string. If the
  16041.      string starts with valid numeric data, this will be the value
  16042.      used. Otherwise, the value will be 0 (zero). Valid numeric data
  16043.      is an optional sign, followed by one or more digits (optionally
  16044.      containing a decimal point), followed by an optional
  16045.      exponent. The exponent is an 'e' or 'E' followed by one or more
  16046.      digits.
  16047.     </P
  16048. ><DIV
  16049. CLASS="informalexample"
  16050. ><P
  16051. ></P
  16052. ><A
  16053. NAME="AEN2990"
  16054. ></A
  16055. ><TABLE
  16056. BORDER="0"
  16057. BGCOLOR="#E0E0E0"
  16058. CELLPADDING="5"
  16059. ><TR
  16060. ><TD
  16061. ><PRE
  16062. CLASS="php"
  16063. ><?php
  16064. $foo = 1 + "10.5";                // $foo is float (11.5)
  16065. $foo = 1 + "-1.3e3";              // $foo is float (-1299)
  16066. $foo = 1 + "bob-1.3e3";           // $foo is integer (1)
  16067. $foo = 1 + "bob3";                // $foo is integer (1)
  16068. $foo = 1 + "10 Small Pigs";       // $foo is integer (11)
  16069. $foo = 4 + "10.2 Little Piggies"; // $foo is float (14.2)
  16070. $foo = "10.0 pigs " + 1;          // $foo is float (11)
  16071. $foo = "10.0 pigs " + 1.0;        // $foo is float (11)     
  16072. ?></PRE
  16073. ></TD
  16074. ></TR
  16075. ></TABLE
  16076. ><P
  16077. ></P
  16078. ></DIV
  16079. ><P
  16080. >      For more information on this conversion, see the Unix manual page
  16081.      for strtod(3).
  16082.     </P
  16083. ><P
  16084. >      If you would like to test any of the examples in this section,
  16085.      you can cut and paste the examples and insert the following line
  16086.      to see for yourself what's going on:
  16087.      <DIV
  16088. CLASS="informalexample"
  16089. ><P
  16090. ></P
  16091. ><A
  16092. NAME="AEN2994"
  16093. ></A
  16094. ><TABLE
  16095. BORDER="0"
  16096. BGCOLOR="#E0E0E0"
  16097. CELLPADDING="5"
  16098. ><TR
  16099. ><TD
  16100. ><PRE
  16101. CLASS="php"
  16102. ><?php
  16103. echo "\$foo==$foo; type is " . gettype ($foo) . "<br />\n";
  16104. ?></PRE
  16105. ></TD
  16106. ></TR
  16107. ></TABLE
  16108. ><P
  16109. ></P
  16110. ></DIV
  16111. >
  16112.     </P
  16113. ><P
  16114. >      Do not expect to get the code of one character by converting it
  16115.      to integer (as you would do in C for example). Use the functions
  16116.      <A
  16117. HREF="#function.ord"
  16118. ><B
  16119. CLASS="function"
  16120. >ord()</B
  16121. ></A
  16122. > and <A
  16123. HREF="#function.chr"
  16124. ><B
  16125. CLASS="function"
  16126. >chr()</B
  16127. ></A
  16128. > to convert
  16129.      between charcodes and characters.
  16130.     </P
  16131. ></DIV
  16132. ></DIV
  16133. ><DIV
  16134. CLASS="sect1"
  16135. ><HR><H2
  16136. CLASS="sect1"
  16137. ><A
  16138. NAME="language.types.array"
  16139. >Arrays</A
  16140. ></H2
  16141. ><P
  16142. >     An array in PHP is actually an ordered map. A map is a type that
  16143.     maps <SPAN
  16144. CLASS="emphasis"
  16145. ><I
  16146. CLASS="emphasis"
  16147. >values</I
  16148. ></SPAN
  16149. > to <SPAN
  16150. CLASS="emphasis"
  16151. ><I
  16152. CLASS="emphasis"
  16153. >keys</I
  16154. ></SPAN
  16155. >. 
  16156.     This type is optimized in several ways,
  16157.     so you can use it as a real array, or a list (vector), 
  16158.     hashtable (which is an implementation of a map), 
  16159.     dictionary, collection,
  16160.     stack, queue and probably more. Because you can have another
  16161.     PHP array as a value, you can also quite easily simulate
  16162.     trees.
  16163.    </P
  16164. ><P
  16165. >     Explanation of those data structures is beyond the scope of this
  16166.     manual, but you'll find at least one example for each of them.
  16167.     For more information we refer you to external literature about
  16168.     this broad topic.
  16169.    </P
  16170. ><DIV
  16171. CLASS="sect2"
  16172. ><HR><H3
  16173. CLASS="sect2"
  16174. ><A
  16175. NAME="language.types.array.syntax"
  16176. >Syntax</A
  16177. ></H3
  16178. ><DIV
  16179. CLASS="sect3"
  16180. ><H4
  16181. CLASS="sect3"
  16182. ><A
  16183. NAME="language.types.array.syntax.array-func"
  16184. >Specifying with <A
  16185. HREF="#function.array"
  16186. ><B
  16187. CLASS="function"
  16188. >array()</B
  16189. ></A
  16190. ></A
  16191. ></H4
  16192. ><P
  16193. >       An <A
  16194. HREF="#language.types.array"
  16195. ><B
  16196. CLASS="type"
  16197. >array</B
  16198. ></A
  16199. > can be created by the <A
  16200. HREF="#function.array"
  16201. ><B
  16202. CLASS="function"
  16203. >array()</B
  16204. ></A
  16205. > 
  16206.       language-construct. It takes a certain number of comma-separated
  16207.       <VAR
  16208. CLASS="literal"
  16209. ><VAR
  16210. CLASS="replaceable"
  16211. >key</VAR
  16212. > => <VAR
  16213. CLASS="replaceable"
  16214. >value</VAR
  16215. ></VAR
  16216. >
  16217.       pairs.
  16218.      </P
  16219. ><P
  16220. >       <TABLE
  16221. BORDER="0"
  16222. BGCOLOR="#E0E0E0"
  16223. CELLPADDING="5"
  16224. ><TR
  16225. ><TD
  16226. ><PRE
  16227. CLASS="synopsis"
  16228. >array( [<VAR
  16229. CLASS="replaceable"
  16230. >key</VAR
  16231. > =>] <VAR
  16232. CLASS="replaceable"
  16233. >value</VAR
  16234. >
  16235.      , ...
  16236.      )
  16237. // <VAR
  16238. CLASS="replaceable"
  16239. >key</VAR
  16240. > may be an <A
  16241. HREF="#language.types.integer"
  16242. ><B
  16243. CLASS="type"
  16244. >integer</B
  16245. ></A
  16246. > or <A
  16247. HREF="#language.types.string"
  16248. ><B
  16249. CLASS="type"
  16250. >string</B
  16251. ></A
  16252. >
  16253. // <VAR
  16254. CLASS="replaceable"
  16255. >value</VAR
  16256. > may be any value</PRE
  16257. ></TD
  16258. ></TR
  16259. ></TABLE
  16260. >
  16261.      </P
  16262. ><P
  16263. >       <DIV
  16264. CLASS="informalexample"
  16265. ><P
  16266. ></P
  16267. ><A
  16268. NAME="AEN3026"
  16269. ></A
  16270. ><TABLE
  16271. BORDER="0"
  16272. BGCOLOR="#E0E0E0"
  16273. CELLPADDING="5"
  16274. ><TR
  16275. ><TD
  16276. ><PRE
  16277. CLASS="php"
  16278. ><?php
  16279. $arr = array("foo" => "bar", 12 => true);
  16280.  
  16281. echo $arr["foo"]; // bar
  16282. echo $arr[12];    // 1
  16283. ?></PRE
  16284. ></TD
  16285. ></TR
  16286. ></TABLE
  16287. ><P
  16288. ></P
  16289. ></DIV
  16290. >
  16291.      </P
  16292. ><P
  16293. >       A <VAR
  16294. CLASS="varname"
  16295. >key</VAR
  16296. > may be either an
  16297.       <VAR
  16298. CLASS="literal"
  16299. >integer</VAR
  16300. > or a <A
  16301. HREF="#language.types.string"
  16302. ><B
  16303. CLASS="type"
  16304. >string</B
  16305. ></A
  16306. >. If a key is
  16307.       the standard representation of an <A
  16308. HREF="#language.types.integer"
  16309. ><B
  16310. CLASS="type"
  16311. >integer</B
  16312. ></A
  16313. >, it will
  16314.       be interpreted as such (i.e.  <VAR
  16315. CLASS="literal"
  16316. >"8"</VAR
  16317. > will be
  16318.       interpreted as <VAR
  16319. CLASS="literal"
  16320. >8</VAR
  16321. >, while
  16322.       <VAR
  16323. CLASS="literal"
  16324. >"08"</VAR
  16325. > will be interpreted as
  16326.       <VAR
  16327. CLASS="literal"
  16328. >"08"</VAR
  16329. >). There are no different indexed and
  16330.       associative array types in PHP; there is only one array type,
  16331.       which can both contain integer and string indices.
  16332.      </P
  16333. ><P
  16334. >       A value can be of any PHP type.
  16335.       <DIV
  16336. CLASS="informalexample"
  16337. ><P
  16338. ></P
  16339. ><A
  16340. NAME="AEN3038"
  16341. ></A
  16342. ><TABLE
  16343. BORDER="0"
  16344. BGCOLOR="#E0E0E0"
  16345. CELLPADDING="5"
  16346. ><TR
  16347. ><TD
  16348. ><PRE
  16349. CLASS="php"
  16350. ><?php
  16351. $arr = array("somearray" => array(6 => 5, 13 => 9, "a" => 42));
  16352.  
  16353. echo $arr["somearray"][6];    // 5
  16354. echo $arr["somearray"][13];   // 9
  16355. echo $arr["somearray"]["a"];  // 42
  16356. ?></PRE
  16357. ></TD
  16358. ></TR
  16359. ></TABLE
  16360. ><P
  16361. ></P
  16362. ></DIV
  16363. >
  16364.      </P
  16365. ><P
  16366. >       If you do not specify a key for a given value, then the maximum
  16367.       of the integer indices is taken, and the new key will be that
  16368.       maximum value + 1. If you specify a key that already has a value
  16369.       assigned to it, that value will be overwritten.
  16370.       <DIV
  16371. CLASS="informalexample"
  16372. ><P
  16373. ></P
  16374. ><A
  16375. NAME="AEN3041"
  16376. ></A
  16377. ><TABLE
  16378. BORDER="0"
  16379. BGCOLOR="#E0E0E0"
  16380. CELLPADDING="5"
  16381. ><TR
  16382. ><TD
  16383. ><PRE
  16384. CLASS="php"
  16385. ><?php
  16386. // This array is the same as ...
  16387. array(5 => 43, 32, 56, "b" => 12);
  16388.  
  16389. // ...this array
  16390. array(5 => 43, 6 => 32, 7 => 56, "b" => 12);
  16391. ?></PRE
  16392. ></TD
  16393. ></TR
  16394. ></TABLE
  16395. ><P
  16396. ></P
  16397. ></DIV
  16398. >
  16399.      </P
  16400. ><DIV
  16401. CLASS="warning"
  16402. ><P
  16403. ></P
  16404. ><TABLE
  16405. CLASS="warning"
  16406. BORDER="1"
  16407. WIDTH="100%"
  16408. ><TR
  16409. ><TD
  16410. ALIGN="CENTER"
  16411. ><B
  16412. >Warning</B
  16413. ></TD
  16414. ></TR
  16415. ><TR
  16416. ><TD
  16417. ALIGN="LEFT"
  16418. ><P
  16419. >          As of PHP 4.3.0, the index generation behaviour described
  16420.          above has changed. Now, if you append to an array in which
  16421.          the current maximum key is negative, then the next key
  16422.          created will be zero (<VAR
  16423. CLASS="literal"
  16424. >0</VAR
  16425. >). Before, the new
  16426.          index would have been set to the largest existing key + 1,
  16427.          the same as positive indices are.
  16428.       </P
  16429. ></TD
  16430. ></TR
  16431. ></TABLE
  16432. ></DIV
  16433. ><P
  16434. >       Using <TT
  16435. CLASS="constant"
  16436. ><B
  16437. >TRUE</B
  16438. ></TT
  16439. > as a key will evaluate to <A
  16440. HREF="#language.types.integer"
  16441. ><B
  16442. CLASS="type"
  16443. >integer</B
  16444. ></A
  16445. >
  16446.       <VAR
  16447. CLASS="literal"
  16448. >1</VAR
  16449. > as key. Using <TT
  16450. CLASS="constant"
  16451. ><B
  16452. >FALSE</B
  16453. ></TT
  16454. > as a key will evaluate
  16455.       to <A
  16456. HREF="#language.types.integer"
  16457. ><B
  16458. CLASS="type"
  16459. >integer</B
  16460. ></A
  16461. > <VAR
  16462. CLASS="literal"
  16463. >0</VAR
  16464. > as key. Using
  16465.       <VAR
  16466. CLASS="literal"
  16467. >NULL</VAR
  16468. > as a key will evaluate to the empty
  16469.       string. Using the empty string as key will create (or overwrite)
  16470.       a key with the empty string and its value; it is not the same as
  16471.       using empty brackets.
  16472.      </P
  16473. ><P
  16474. >       You cannot use arrays or objects as keys. Doing so will result in a
  16475.       warning: <VAR
  16476. CLASS="literal"
  16477. >Illegal offset type</VAR
  16478. >.
  16479.      </P
  16480. ></DIV
  16481. ><DIV
  16482. CLASS="sect3"
  16483. ><HR><H4
  16484. CLASS="sect3"
  16485. ><A
  16486. NAME="language.types.array.syntax.modifying"
  16487. >Creating/modifying with square-bracket syntax</A
  16488. ></H4
  16489. ><P
  16490. >       You can also modify an existing array by explicitly setting
  16491.       values in it.
  16492.      </P
  16493. ><P
  16494. >       This is done by assigning values to the array while specifying the 
  16495.       key in brackets. You can also omit the key, add an empty pair
  16496.       of brackets ("<VAR
  16497. CLASS="literal"
  16498. >[]</VAR
  16499. >") to the variable name in that case.
  16500.       <TABLE
  16501. BORDER="0"
  16502. BGCOLOR="#E0E0E0"
  16503. CELLPADDING="5"
  16504. ><TR
  16505. ><TD
  16506. ><PRE
  16507. CLASS="synopsis"
  16508. >$arr[<VAR
  16509. CLASS="replaceable"
  16510. >key</VAR
  16511. >] = <VAR
  16512. CLASS="replaceable"
  16513. >value</VAR
  16514. >;
  16515. $arr[] = <VAR
  16516. CLASS="replaceable"
  16517. >value</VAR
  16518. >;
  16519. // <VAR
  16520. CLASS="replaceable"
  16521. >key</VAR
  16522. > may be an <A
  16523. HREF="#language.types.integer"
  16524. ><B
  16525. CLASS="type"
  16526. >integer</B
  16527. ></A
  16528. > or <A
  16529. HREF="#language.types.string"
  16530. ><B
  16531. CLASS="type"
  16532. >string</B
  16533. ></A
  16534. >
  16535. // <VAR
  16536. CLASS="replaceable"
  16537. >value</VAR
  16538. > may be any value</PRE
  16539. ></TD
  16540. ></TR
  16541. ></TABLE
  16542. >
  16543.       If <VAR
  16544. CLASS="varname"
  16545. >$arr</VAR
  16546. > doesn't exist yet, it will be created. 
  16547.       So this is also an alternative way to specify an array.
  16548.       To change a certain value, just assign a new value
  16549.       to an element specified with its key. If you want to
  16550.       remove a key/value pair, you need to <A
  16551. HREF="#function.unset"
  16552. ><B
  16553. CLASS="function"
  16554. >unset()</B
  16555. ></A
  16556. > it. 
  16557.       <DIV
  16558. CLASS="informalexample"
  16559. ><P
  16560. ></P
  16561. ><A
  16562. NAME="AEN3071"
  16563. ></A
  16564. ><TABLE
  16565. BORDER="0"
  16566. BGCOLOR="#E0E0E0"
  16567. CELLPADDING="5"
  16568. ><TR
  16569. ><TD
  16570. ><PRE
  16571. CLASS="php"
  16572. ><?php
  16573. $arr = array(5 => 1, 12 => 2);
  16574.  
  16575. $arr[] = 56;    // This is the same as $arr[13] = 56;
  16576.                 // at this point of the script
  16577.  
  16578. $arr["x"] = 42; // This adds a new element to
  16579.                 // the array with key "x"
  16580.                 
  16581. unset($arr[5]); // This removes the element from the array
  16582.  
  16583. unset($arr);    // This deletes the whole array
  16584. ?></PRE
  16585. ></TD
  16586. ></TR
  16587. ></TABLE
  16588. ><P
  16589. ></P
  16590. ></DIV
  16591. >
  16592.      </P
  16593. ><DIV
  16594. CLASS="note"
  16595. ><BLOCKQUOTE
  16596. CLASS="note"
  16597. ><P
  16598. ><B
  16599. >Note: </B
  16600. >
  16601.        As mentioned above, if you provide the brackets with no key
  16602.        specified, then the maximum of the existing integer indices is
  16603.        taken, and the new key will be that maximum value + 1 . If no
  16604.        integer indices exist yet, the key will be <VAR
  16605. CLASS="literal"
  16606. >0</VAR
  16607. >
  16608.        (zero). If you specify a key that already has a value assigned
  16609.        to it, that value will be overwritten.
  16610.       </P
  16611. ><P
  16612. >        <DIV
  16613. CLASS="warning"
  16614. ><P
  16615. ></P
  16616. ><TABLE
  16617. CLASS="warning"
  16618. BORDER="1"
  16619. WIDTH="100%"
  16620. ><TR
  16621. ><TD
  16622. ALIGN="CENTER"
  16623. ><B
  16624. >Warning</B
  16625. ></TD
  16626. ></TR
  16627. ><TR
  16628. ><TD
  16629. ALIGN="LEFT"
  16630. ><P
  16631. >          As of PHP 4.3.0, the index generation behaviour described
  16632.          above has changed. Now, if you append to an array in which
  16633.          the current maximum key is negative, then the next key
  16634.          created will be zero (<VAR
  16635. CLASS="literal"
  16636. >0</VAR
  16637. >). Before, the new
  16638.          index would have been set to the largest existing key + 1,
  16639.          the same as positive indices are.
  16640.         </P
  16641. ></TD
  16642. ></TR
  16643. ></TABLE
  16644. ></DIV
  16645. >
  16646.       </P
  16647. ><P
  16648. >        Note that the maximum integer key used for this <SPAN
  16649. CLASS="emphasis"
  16650. ><I
  16651. CLASS="emphasis"
  16652. >need
  16653.        not currently exist in the array</I
  16654. ></SPAN
  16655. >. It simply must
  16656.        have existed in the array at some time since the last time the
  16657.        array was re-indexed. The following example illustrates:
  16658.       </P
  16659. ><DIV
  16660. CLASS="informalexample"
  16661. ><P
  16662. ></P
  16663. ><A
  16664. NAME="AEN3082"
  16665. ></A
  16666. ><TABLE
  16667. BORDER="0"
  16668. BGCOLOR="#E0E0E0"
  16669. CELLPADDING="5"
  16670. ><TR
  16671. ><TD
  16672. ><PRE
  16673. CLASS="php"
  16674. ><?php
  16675. // Create a simple array.
  16676. $array = array(1, 2, 3, 4, 5);
  16677. print_r($array);
  16678.  
  16679. // Now delete every item, but leave the array itself intact:
  16680. foreach ($array as $i => $value) {
  16681.     unset($array[$i]);
  16682. }
  16683. print_r($array);
  16684.  
  16685. // Append an item (note that the new key is 5, instead of 0 as you
  16686. // might expect).
  16687. $array[] = 6;
  16688. print_r($array);
  16689.  
  16690. // Re-index:
  16691. $array = array_values($array);
  16692. $array[] = 7;
  16693. print_r($array);
  16694. ?></PRE
  16695. ></TD
  16696. ></TR
  16697. ></TABLE
  16698. ><P
  16699. >         The above example would produce the following output:
  16700.         <TABLE
  16701. BORDER="0"
  16702. BGCOLOR="#E0E0E0"
  16703. CELLPADDING="5"
  16704. ><TR
  16705. ><TD
  16706. ><PRE
  16707. CLASS="screen"
  16708. >Array
  16709. (
  16710.     [0] => 1
  16711.     [1] => 2
  16712.     [2] => 3
  16713.     [3] => 4
  16714.     [4] => 5
  16715. )
  16716. Array
  16717. (
  16718. )
  16719. Array
  16720. (
  16721.     [5] => 6
  16722. )
  16723. Array
  16724. (
  16725.     [0] => 6
  16726.     [1] => 7
  16727. )</PRE
  16728. ></TD
  16729. ></TR
  16730. ></TABLE
  16731. >
  16732.        </P
  16733. ><P
  16734. ></P
  16735. ></DIV
  16736. ></BLOCKQUOTE
  16737. ></DIV
  16738. ></DIV
  16739. ></DIV
  16740. ><DIV
  16741. CLASS="sect2"
  16742. ><HR><H3
  16743. CLASS="sect2"
  16744. ><A
  16745. NAME="language.types.array.useful-funcs"
  16746. >Useful functions</A
  16747. ></H3
  16748. ><P
  16749. >      There are quite a few useful functions for working with arrays.
  16750.      See the <A
  16751. HREF="#ref.array"
  16752. >array functions</A
  16753. > section.
  16754.     </P
  16755. ><DIV
  16756. CLASS="note"
  16757. ><BLOCKQUOTE
  16758. CLASS="note"
  16759. ><P
  16760. ><B
  16761. >Note: </B
  16762. >
  16763.       The <A
  16764. HREF="#function.unset"
  16765. ><B
  16766. CLASS="function"
  16767. >unset()</B
  16768. ></A
  16769. > function allows unsetting keys of an 
  16770.       array. Be aware that the array will NOT be reindexed. If you only
  16771.       use "usual integer indices" (starting from zero, increasing by one),
  16772.       you can achieve the reindex effect by using <A
  16773. HREF="#function.array-values"
  16774. ><B
  16775. CLASS="function"
  16776. >array_values()</B
  16777. ></A
  16778. >.
  16779.       <DIV
  16780. CLASS="informalexample"
  16781. ><P
  16782. ></P
  16783. ><A
  16784. NAME="AEN3094"
  16785. ></A
  16786. ><TABLE
  16787. BORDER="0"
  16788. BGCOLOR="#E0E0E0"
  16789. CELLPADDING="5"
  16790. ><TR
  16791. ><TD
  16792. ><PRE
  16793. CLASS="php"
  16794. ><?php
  16795. $a = array(1 => 'one', 2 => 'two', 3 => 'three');
  16796. unset($a[2]);
  16797. /* will produce an array that would have been defined as
  16798.    $a = array(1 => 'one', 3 => 'three');
  16799.    and NOT
  16800.    $a = array(1 => 'one', 2 =>'three');
  16801. */
  16802.  
  16803. $b = array_values($a);
  16804. // Now $b is array(0 => 'one', 1 =>'three')
  16805. ?></PRE
  16806. ></TD
  16807. ></TR
  16808. ></TABLE
  16809. ><P
  16810. ></P
  16811. ></DIV
  16812. >
  16813.      
  16814.      </P
  16815. ></BLOCKQUOTE
  16816. ></DIV
  16817. ><P
  16818. >      The <A
  16819. HREF="#control-structures.foreach"
  16820. >foreach</A
  16821. > 
  16822.      control structure exists specifically for arrays. It 
  16823.      provides an easy way to traverse an array.
  16824.     </P
  16825. ></DIV
  16826. ><DIV
  16827. CLASS="sect2"
  16828. ><HR><H3
  16829. CLASS="sect2"
  16830. ><A
  16831. NAME="language.types.array.donts"
  16832. >Array do's and don'ts</A
  16833. ></H3
  16834. ><DIV
  16835. CLASS="sect3"
  16836. ><H4
  16837. CLASS="sect3"
  16838. ><A
  16839. NAME="language.types.array.foo-bar"
  16840. >Why is <VAR
  16841. CLASS="literal"
  16842. >$foo[bar]</VAR
  16843. > wrong?</A
  16844. ></H4
  16845. ><P
  16846. >       You should always use quotes around a string literal
  16847.       array index.  For example, use $foo['bar'] and not
  16848.       $foo[bar]. But why is $foo[bar] wrong? You might have seen the
  16849.       following syntax in old scripts:
  16850.       <DIV
  16851. CLASS="informalexample"
  16852. ><P
  16853. ></P
  16854. ><A
  16855. NAME="AEN3104"
  16856. ></A
  16857. ><TABLE
  16858. BORDER="0"
  16859. BGCOLOR="#E0E0E0"
  16860. CELLPADDING="5"
  16861. ><TR
  16862. ><TD
  16863. ><PRE
  16864. CLASS="php"
  16865. ><?php
  16866. $foo[bar] = 'enemy';
  16867. echo $foo[bar];
  16868. // etc
  16869. ?></PRE
  16870. ></TD
  16871. ></TR
  16872. ></TABLE
  16873. ><P
  16874. ></P
  16875. ></DIV
  16876. >
  16877.       This is wrong, but it works. Then, why is it wrong? The reason
  16878.       is that this code has an undefined constant (bar) rather than a
  16879.       string ('bar' - notice the quotes), and PHP may in future define
  16880.       constants which, unfortunately for your code, have the same
  16881.       name.  It works because PHP automatically converts a
  16882.       <SPAN
  16883. CLASS="emphasis"
  16884. ><I
  16885. CLASS="emphasis"
  16886. >bare string</I
  16887. ></SPAN
  16888. > (an unquoted string which does
  16889.       not correspond to any known symbol) into a string which contains
  16890.       the bare string. For instance, if there is no defined constant
  16891.       named <TT
  16892. CLASS="constant"
  16893. ><B
  16894. >bar</B
  16895. ></TT
  16896. >, then PHP will substitute in the
  16897.       string <VAR
  16898. CLASS="literal"
  16899. >'bar'</VAR
  16900. > and use that.
  16901.      </P
  16902. ><DIV
  16903. CLASS="note"
  16904. ><BLOCKQUOTE
  16905. CLASS="note"
  16906. ><P
  16907. ><B
  16908. >Note: </B
  16909. >
  16910.        This does not mean to <SPAN
  16911. CLASS="emphasis"
  16912. ><I
  16913. CLASS="emphasis"
  16914. >always</I
  16915. ></SPAN
  16916. > quote the
  16917.        key. You do not want to quote keys which are <A
  16918. HREF="#language.constants"
  16919. >constants</A
  16920. > or <A
  16921. HREF="#language.variables"
  16922. >variables</A
  16923. >, as this will
  16924.        prevent PHP from interpreting them.
  16925.       </P
  16926. ><DIV
  16927. CLASS="informalexample"
  16928. ><P
  16929. ></P
  16930. ><A
  16931. NAME="AEN3114"
  16932. ></A
  16933. ><TABLE
  16934. BORDER="0"
  16935. BGCOLOR="#E0E0E0"
  16936. CELLPADDING="5"
  16937. ><TR
  16938. ><TD
  16939. ><PRE
  16940. CLASS="php"
  16941. ><?php
  16942. error_reporting(E_ALL);
  16943. ini_set('display_errors', true);
  16944. ini_set('html_errors', false);
  16945. // Simple array:
  16946. $array = array(1, 2);
  16947. $count = count($array);
  16948. for ($i = 0; $i < $count; $i++) {
  16949.     echo "\nChecking $i: \n";
  16950.     echo "Bad: " . $array['$i'] . "\n";
  16951.     echo "Good: " . $array[$i] . "\n";
  16952.     echo "Bad: {$array['$i']}\n";
  16953.     echo "Good: {$array[$i]}\n";
  16954. }
  16955. ?></PRE
  16956. ></TD
  16957. ></TR
  16958. ></TABLE
  16959. ><P
  16960. ></P
  16961. ></DIV
  16962. ><P
  16963. ><B
  16964. >Note: </B
  16965. >
  16966.        The output from the above is:
  16967.        <TABLE
  16968. BORDER="0"
  16969. BGCOLOR="#E0E0E0"
  16970. CELLPADDING="5"
  16971. ><TR
  16972. ><TD
  16973. ><PRE
  16974. CLASS="screen"
  16975. >Checking 0: 
  16976. Notice: Undefined index:  $i in /path/to/script.html on line 9
  16977. Bad: 
  16978. Good: 1
  16979. Notice: Undefined index:  $i in /path/to/script.html on line 11
  16980. Bad: 
  16981. Good: 1
  16982.  
  16983. Checking 1: 
  16984. Notice: Undefined index:  $i in /path/to/script.html on line 9
  16985. Bad: 
  16986. Good: 2
  16987. Notice: Undefined index:  $i in /path/to/script.html on line 11
  16988. Bad: 
  16989. Good: 2</PRE
  16990. ></TD
  16991. ></TR
  16992. ></TABLE
  16993. >
  16994.       </P
  16995. ></BLOCKQUOTE
  16996. ></DIV
  16997. ><P
  16998. >       More examples to demonstrate this fact:
  16999.       <DIV
  17000. CLASS="informalexample"
  17001. ><P
  17002. ></P
  17003. ><A
  17004. NAME="AEN3119"
  17005. ></A
  17006. ><TABLE
  17007. BORDER="0"
  17008. BGCOLOR="#E0E0E0"
  17009. CELLPADDING="5"
  17010. ><TR
  17011. ><TD
  17012. ><PRE
  17013. CLASS="php"
  17014. ><?php
  17015. // Let's show all errors
  17016. error_reporting(E_ALL);
  17017.  
  17018. $arr = array('fruit' => 'apple', 'veggie' => 'carrot');
  17019.  
  17020. // Correct
  17021. print $arr['fruit'];  // apple
  17022. print $arr['veggie']; // carrot
  17023.  
  17024. // Incorrect.  This works but also throws a PHP error of
  17025. // level E_NOTICE because of an undefined constant named fruit
  17026. // 
  17027. // Notice: Use of undefined constant fruit - assumed 'fruit' in...
  17028. print $arr[fruit];    // apple
  17029.  
  17030. // Let's define a constant to demonstrate what's going on.  We
  17031. // will assign value 'veggie' to a constant named fruit.
  17032. define('fruit', 'veggie');
  17033.  
  17034. // Notice the difference now
  17035. print $arr['fruit'];  // apple
  17036. print $arr[fruit];    // carrot
  17037.  
  17038. // The following is okay as it's inside a string.  Constants are not
  17039. // looked for within strings so no E_NOTICE error here
  17040. print "Hello $arr[fruit]";      // Hello apple
  17041.  
  17042. // With one exception, braces surrounding arrays within strings
  17043. // allows constants to be looked for
  17044. print "Hello {$arr[fruit]}";    // Hello carrot
  17045. print "Hello {$arr['fruit']}";  // Hello apple
  17046.  
  17047. // This will not work, results in a parse error such as:
  17048. // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
  17049. // This of course applies to using autoglobals in strings as well
  17050. print "Hello $arr['fruit']";
  17051. print "Hello $_GET['foo']";
  17052.  
  17053. // Concatenation is another option
  17054. print "Hello " . $arr['fruit']; // Hello apple
  17055. ?></PRE
  17056. ></TD
  17057. ></TR
  17058. ></TABLE
  17059. ><P
  17060. ></P
  17061. ></DIV
  17062. >
  17063.      </P
  17064. ><P
  17065. >       When you turn <A
  17066. HREF="#function.error-reporting"
  17067. ><B
  17068. CLASS="function"
  17069. >error_reporting()</B
  17070. ></A
  17071. > up to show
  17072.       <TT
  17073. CLASS="constant"
  17074. ><B
  17075. >E_NOTICE</B
  17076. ></TT
  17077. > level errors (such as setting
  17078.       it to <TT
  17079. CLASS="constant"
  17080. ><B
  17081. >E_ALL</B
  17082. ></TT
  17083. >) then you will see these
  17084.       errors.  By default, <A
  17085. HREF="#ini.error-reporting"
  17086. >       error_reporting</A
  17087. > is turned down to not show them.
  17088.      </P
  17089. ><P
  17090. >       As stated in the <A
  17091. HREF="#language.types.array.syntax"
  17092. >syntax</A
  17093. > section,
  17094.       there must be an expression between the square brackets
  17095.       ('<VAR
  17096. CLASS="literal"
  17097. >[</VAR
  17098. >' and '<VAR
  17099. CLASS="literal"
  17100. >]</VAR
  17101. >').  That means
  17102.       that you can write things like this:
  17103.       <DIV
  17104. CLASS="informalexample"
  17105. ><P
  17106. ></P
  17107. ><A
  17108. NAME="AEN3130"
  17109. ></A
  17110. ><TABLE
  17111. BORDER="0"
  17112. BGCOLOR="#E0E0E0"
  17113. CELLPADDING="5"
  17114. ><TR
  17115. ><TD
  17116. ><PRE
  17117. CLASS="php"
  17118. ><?php
  17119. echo $arr[somefunc($bar)];
  17120. ?></PRE
  17121. ></TD
  17122. ></TR
  17123. ></TABLE
  17124. ><P
  17125. ></P
  17126. ></DIV
  17127. >
  17128.       This is an example of using a function return value
  17129.       as the array index. PHP also knows about constants,
  17130.       as you may have seen the <VAR
  17131. CLASS="literal"
  17132. >E_*</VAR
  17133. > ones
  17134.       before.      
  17135.  
  17136.       <DIV
  17137. CLASS="informalexample"
  17138. ><P
  17139. ></P
  17140. ><A
  17141. NAME="AEN3133"
  17142. ></A
  17143. ><TABLE
  17144. BORDER="0"
  17145. BGCOLOR="#E0E0E0"
  17146. CELLPADDING="5"
  17147. ><TR
  17148. ><TD
  17149. ><PRE
  17150. CLASS="php"
  17151. ><?php
  17152. $error_descriptions[E_ERROR]   = "A fatal error has occured";
  17153. $error_descriptions[E_WARNING] = "PHP issued a warning";
  17154. $error_descriptions[E_NOTICE]  = "This is just an informal notice";
  17155. ?></PRE
  17156. ></TD
  17157. ></TR
  17158. ></TABLE
  17159. ><P
  17160. ></P
  17161. ></DIV
  17162. >
  17163.       Note that <VAR
  17164. CLASS="literal"
  17165. >E_ERROR</VAR
  17166. > is also a valid identifier, 
  17167.       just like <VAR
  17168. CLASS="literal"
  17169. >bar</VAR
  17170. > in the first example. But the last
  17171.       example is in fact the same as writing:
  17172.       <DIV
  17173. CLASS="informalexample"
  17174. ><P
  17175. ></P
  17176. ><A
  17177. NAME="AEN3137"
  17178. ></A
  17179. ><TABLE
  17180. BORDER="0"
  17181. BGCOLOR="#E0E0E0"
  17182. CELLPADDING="5"
  17183. ><TR
  17184. ><TD
  17185. ><PRE
  17186. CLASS="php"
  17187. ><?php
  17188. $error_descriptions[1] = "A fatal error has occured";
  17189. $error_descriptions[2] = "PHP issued a warning";
  17190. $error_descriptions[8] = "This is just an informal notice";
  17191. ?></PRE
  17192. ></TD
  17193. ></TR
  17194. ></TABLE
  17195. ><P
  17196. ></P
  17197. ></DIV
  17198. >
  17199.       because <VAR
  17200. CLASS="literal"
  17201. >E_ERROR</VAR
  17202. > equals <VAR
  17203. CLASS="literal"
  17204. >1</VAR
  17205. >, etc.
  17206.      </P
  17207. ><P
  17208. >       As we already explained in the above examples, 
  17209.       <VAR
  17210. CLASS="literal"
  17211. >$foo[bar]</VAR
  17212. > still works but is wrong.
  17213.       It works, because <VAR
  17214. CLASS="literal"
  17215. >bar</VAR
  17216. > is due to its syntax
  17217.       expected to be a constant expression. However, in this case no 
  17218.       constant with the name <VAR
  17219. CLASS="literal"
  17220. >bar</VAR
  17221. > exists. PHP now
  17222.       assumes that you meant <VAR
  17223. CLASS="literal"
  17224. >bar</VAR
  17225. > literally, 
  17226.       as the string <VAR
  17227. CLASS="literal"
  17228. >"bar"</VAR
  17229. >, but that you forgot
  17230.       to write the quotes.
  17231.      </P
  17232. ><DIV
  17233. CLASS="sect4"
  17234. ><HR><H5
  17235. CLASS="sect4"
  17236. ><A
  17237. NAME="AEN3147"
  17238. >So why is it bad then?</A
  17239. ></H5
  17240. ><P
  17241. >        At some point in the future, the PHP team might want to add another
  17242.        constant or keyword, or you may introduce another constant into your
  17243.        application, and then you get in trouble. For example,
  17244.        you already cannot use the words <VAR
  17245. CLASS="literal"
  17246. >empty</VAR
  17247. > and 
  17248.        <VAR
  17249. CLASS="literal"
  17250. >default</VAR
  17251. > this way, since they are special 
  17252.        <A
  17253. HREF="#reserved"
  17254. >reserved keywords</A
  17255. >.
  17256.       </P
  17257. ><DIV
  17258. CLASS="note"
  17259. ><BLOCKQUOTE
  17260. CLASS="note"
  17261. ><P
  17262. ><B
  17263. >Note: </B
  17264. >
  17265.         To reiterate, inside a double-quoted <A
  17266. HREF="#language.types.string"
  17267. ><B
  17268. CLASS="type"
  17269. >string</B
  17270. ></A
  17271. >, it's
  17272.         valid to not surround array indexes with quotes so
  17273.         <VAR
  17274. CLASS="literal"
  17275. >"$foo[bar]"</VAR
  17276. > is valid.  See the above 
  17277.         examples for details on why as well as the section on
  17278.         <A
  17279. HREF="#language.types.string.parsing"
  17280. >variable parsing 
  17281.         in strings</A
  17282. >.
  17283.        </P
  17284. ></BLOCKQUOTE
  17285. ></DIV
  17286. ></DIV
  17287. ></DIV
  17288. ></DIV
  17289. ><DIV
  17290. CLASS="sect2"
  17291. ><HR><H3
  17292. CLASS="sect2"
  17293. ><A
  17294. NAME="language.types.array.casting"
  17295. >Converting to array</A
  17296. ></H3
  17297. ><P
  17298. >      For any of the types: <A
  17299. HREF="#language.types.integer"
  17300. ><B
  17301. CLASS="type"
  17302. >integer</B
  17303. ></A
  17304. >, <A
  17305. HREF="#language.types.float"
  17306. ><B
  17307. CLASS="type"
  17308. >float</B
  17309. ></A
  17310. >,
  17311.      <A
  17312. HREF="#language.types.string"
  17313. ><B
  17314. CLASS="type"
  17315. >string</B
  17316. ></A
  17317. >, <A
  17318. HREF="#language.types.boolean"
  17319. ><B
  17320. CLASS="type"
  17321. >boolean</B
  17322. ></A
  17323. > and <A
  17324. HREF="#language.types.resource"
  17325. ><B
  17326. CLASS="type"
  17327. >resource</B
  17328. ></A
  17329. >,
  17330.      if you convert a value to an <A
  17331. HREF="#language.types.array"
  17332. ><B
  17333. CLASS="type"
  17334. >array</B
  17335. ></A
  17336. >, you get an array 
  17337.      with one element (with index 0), which is the scalar value you 
  17338.      started with.
  17339.     </P
  17340. ><P
  17341. >      If you convert an <A
  17342. HREF="#language.types.object"
  17343. ><B
  17344. CLASS="type"
  17345. >object</B
  17346. ></A
  17347. > to an array, you get the
  17348.      properties (member variables) of that object as the array's elements. 
  17349.      The keys are the member variable names.
  17350.     </P
  17351. ><P
  17352. >      If you convert a <TT
  17353. CLASS="constant"
  17354. ><B
  17355. >NULL</B
  17356. ></TT
  17357. > value to an array, you get an empty array.
  17358.     </P
  17359. ></DIV
  17360. ><DIV
  17361. CLASS="sect2"
  17362. ><HR><H3
  17363. CLASS="sect2"
  17364. ><A
  17365. NAME="language.types.array.comparing"
  17366. >Comparing</A
  17367. ></H3
  17368. ><P
  17369. >      It is possible to compare arrays by <A
  17370. HREF="#function.array-diff"
  17371. ><B
  17372. CLASS="function"
  17373. >array_diff()</B
  17374. ></A
  17375. > and
  17376.      by <A
  17377. HREF="#language.operators.array"
  17378. >Array operators</A
  17379. >.
  17380.     </P
  17381. ></DIV
  17382. ><DIV
  17383. CLASS="sect2"
  17384. ><HR><H3
  17385. CLASS="sect2"
  17386. ><A
  17387. NAME="language.types.array.examples"
  17388. >Examples</A
  17389. ></H3
  17390. ><P
  17391. >      The array type in PHP is very versatile, so here will be some 
  17392.      examples to show you the full power of arrays.
  17393.     </P
  17394. ><P
  17395. >       <DIV
  17396. CLASS="informalexample"
  17397. ><P
  17398. ></P
  17399. ><A
  17400. NAME="AEN3180"
  17401. ></A
  17402. ><TABLE
  17403. BORDER="0"
  17404. BGCOLOR="#E0E0E0"
  17405. CELLPADDING="5"
  17406. ><TR
  17407. ><TD
  17408. ><PRE
  17409. CLASS="php"
  17410. ><?php
  17411. // this
  17412. $a = array( 'color' => 'red',
  17413.             'taste' => 'sweet',
  17414.             'shape' => 'round',
  17415.             'name'  => 'apple',
  17416.                        4        // key will be 0
  17417.           );
  17418.  
  17419. // is completely equivalent with
  17420. $a['color'] = 'red';
  17421. $a['taste'] = 'sweet';
  17422. $a['shape'] = 'round';
  17423. $a['name']  = 'apple';
  17424. $a[]        = 4;        // key will be 0
  17425.  
  17426. $b[] = 'a';
  17427. $b[] = 'b';
  17428. $b[] = 'c';
  17429. // will result in the array array(0 => 'a' , 1 => 'b' , 2 => 'c'),
  17430. // or simply array('a', 'b', 'c')
  17431. ?></PRE
  17432. ></TD
  17433. ></TR
  17434. ></TABLE
  17435. ><P
  17436. ></P
  17437. ></DIV
  17438. >
  17439.      </P
  17440. ><TABLE
  17441. WIDTH="100%"
  17442. BORDER="0"
  17443. CELLPADDING="0"
  17444. CELLSPACING="0"
  17445. CLASS="EXAMPLE"
  17446. ><TR
  17447. ><TD
  17448. ><DIV
  17449. CLASS="example"
  17450. ><A
  17451. NAME="AEN3182"
  17452. ></A
  17453. ><P
  17454. ><B
  17455. >Example 11-5. Using array()</B
  17456. ></P
  17457. ><TABLE
  17458. BORDER="0"
  17459. BGCOLOR="#E0E0E0"
  17460. CELLPADDING="5"
  17461. ><TR
  17462. ><TD
  17463. ><PRE
  17464. CLASS="php"
  17465. ><?php
  17466. // Array as (property-)map
  17467. $map = array( 'version'    => 4,
  17468.               'OS'         => 'Linux',
  17469.               'lang'       => 'english',
  17470.               'short_tags' => true
  17471.             );
  17472.             
  17473. // strictly numerical keys
  17474. $array = array( 7,
  17475.                 8,
  17476.                 0,
  17477.                 156,
  17478.                 -10
  17479.               );
  17480. // this is the same as array(0 => 7, 1 => 8, ...)
  17481.  
  17482. $switching = array(         10, // key = 0
  17483.                     5    =>  6,
  17484.                     3    =>  7, 
  17485.                     'a'  =>  4,
  17486.                             11, // key = 6 (maximum of integer-indices was 5)
  17487.                     '8'  =>  2, // key = 8 (integer!)
  17488.                     '02' => 77, // key = '02'
  17489.                     0    => 12  // the value 10 will be overwritten by 12
  17490.                   );
  17491.                   
  17492. // empty array
  17493. $empty = array();         
  17494. ?></PRE
  17495. ></TD
  17496. ></TR
  17497. ></TABLE
  17498. ></DIV
  17499. ></TD
  17500. ></TR
  17501. ></TABLE
  17502. ><TABLE
  17503. WIDTH="100%"
  17504. BORDER="0"
  17505. CELLPADDING="0"
  17506. CELLSPACING="0"
  17507. CLASS="EXAMPLE"
  17508. ><TR
  17509. ><TD
  17510. ><DIV
  17511. CLASS="example"
  17512. ><A
  17513. NAME="language.types.array.examples.loop"
  17514. ></A
  17515. ><P
  17516. ><B
  17517. >Example 11-6. Collection</B
  17518. ></P
  17519. ><TABLE
  17520. BORDER="0"
  17521. BGCOLOR="#E0E0E0"
  17522. CELLPADDING="5"
  17523. ><TR
  17524. ><TD
  17525. ><PRE
  17526. CLASS="php"
  17527. ><?php
  17528. $colors = array('red', 'blue', 'green', 'yellow');
  17529.  
  17530. foreach ($colors as $color) {
  17531.     echo "Do you like $color?\n";
  17532. }
  17533.  
  17534. ?></PRE
  17535. ></TD
  17536. ></TR
  17537. ></TABLE
  17538. ><P
  17539. >       This will output:
  17540.      </P
  17541. ><TABLE
  17542. BORDER="0"
  17543. BGCOLOR="#E0E0E0"
  17544. CELLPADDING="5"
  17545. ><TR
  17546. ><TD
  17547. ><PRE
  17548. CLASS="screen"
  17549. >Do you like red?
  17550. Do you like blue?
  17551. Do you like green?
  17552. Do you like yellow?</PRE
  17553. ></TD
  17554. ></TR
  17555. ></TABLE
  17556. ></DIV
  17557. ></TD
  17558. ></TR
  17559. ></TABLE
  17560. ><P
  17561. >      Note that it is currently not possible to change the values of the array
  17562.      directly in such a loop. 
  17563.       
  17564.      A workaround is the following: 
  17565.      <TABLE
  17566. WIDTH="100%"
  17567. BORDER="0"
  17568. CELLPADDING="0"
  17569. CELLSPACING="0"
  17570. CLASS="EXAMPLE"
  17571. ><TR
  17572. ><TD
  17573. ><DIV
  17574. CLASS="example"
  17575. ><A
  17576. NAME="language.types.array.examples.changeloop"
  17577. ></A
  17578. ><P
  17579. ><B
  17580. >Example 11-7. Collection</B
  17581. ></P
  17582. ><TABLE
  17583. BORDER="0"
  17584. BGCOLOR="#E0E0E0"
  17585. CELLPADDING="5"
  17586. ><TR
  17587. ><TD
  17588. ><PRE
  17589. CLASS="php"
  17590. ><?php
  17591. foreach ($colors as $key => $color) {
  17592.     // won't work:
  17593.     //$color = strtoupper($color);
  17594.     
  17595.     // works:
  17596.     $colors[$key] = strtoupper($color);
  17597. }
  17598. print_r($colors);
  17599. ?></PRE
  17600. ></TD
  17601. ></TR
  17602. ></TABLE
  17603. ><P
  17604. >        This will output:
  17605.       </P
  17606. ><TABLE
  17607. BORDER="0"
  17608. BGCOLOR="#E0E0E0"
  17609. CELLPADDING="5"
  17610. ><TR
  17611. ><TD
  17612. ><PRE
  17613. CLASS="screen"
  17614. >Array
  17615. (
  17616.     [0] => RED
  17617.     [1] => BLUE
  17618.     [2] => GREEN
  17619.     [3] => YELLOW
  17620. )</PRE
  17621. ></TD
  17622. ></TR
  17623. ></TABLE
  17624. ></DIV
  17625. ></TD
  17626. ></TR
  17627. ></TABLE
  17628. >
  17629.     </P
  17630. ><P
  17631. >      This example creates a one-based array.
  17632.      <TABLE
  17633. WIDTH="100%"
  17634. BORDER="0"
  17635. CELLPADDING="0"
  17636. CELLSPACING="0"
  17637. CLASS="EXAMPLE"
  17638. ><TR
  17639. ><TD
  17640. ><DIV
  17641. CLASS="example"
  17642. ><A
  17643. NAME="AEN3197"
  17644. ></A
  17645. ><P
  17646. ><B
  17647. >Example 11-8. One-based index</B
  17648. ></P
  17649. ><TABLE
  17650. BORDER="0"
  17651. BGCOLOR="#E0E0E0"
  17652. CELLPADDING="5"
  17653. ><TR
  17654. ><TD
  17655. ><PRE
  17656. CLASS="php"
  17657. ><?php
  17658. $firstquarter  = array(1 => 'January', 'February', 'March');
  17659. print_r($firstquarter);
  17660. ?></PRE
  17661. ></TD
  17662. ></TR
  17663. ></TABLE
  17664. ><P
  17665. >        This will output:
  17666.       </P
  17667. ><TABLE
  17668. BORDER="0"
  17669. BGCOLOR="#E0E0E0"
  17670. CELLPADDING="5"
  17671. ><TR
  17672. ><TD
  17673. ><PRE
  17674. CLASS="screen"
  17675. >Array 
  17676. (
  17677.     [1] => 'January'
  17678.     [2] => 'February'
  17679.     [3] => 'March'
  17680. )</PRE
  17681. ></TD
  17682. ></TR
  17683. ></TABLE
  17684. ></DIV
  17685. ></TD
  17686. ></TR
  17687. ></TABLE
  17688. >
  17689.     </P
  17690. ><TABLE
  17691. WIDTH="100%"
  17692. BORDER="0"
  17693. CELLPADDING="0"
  17694. CELLSPACING="0"
  17695. CLASS="EXAMPLE"
  17696. ><TR
  17697. ><TD
  17698. ><DIV
  17699. CLASS="example"
  17700. ><A
  17701. NAME="AEN3202"
  17702. ></A
  17703. ><P
  17704. ><B
  17705. >Example 11-9. Filling an array</B
  17706. ></P
  17707. ><TABLE
  17708. BORDER="0"
  17709. BGCOLOR="#E0E0E0"
  17710. CELLPADDING="5"
  17711. ><TR
  17712. ><TD
  17713. ><PRE
  17714. CLASS="php"
  17715. ><?php
  17716. // fill an array with all items from a directory
  17717. $handle = opendir('.');
  17718. while (false !== ($file = readdir($handle))) {
  17719.     $files[] = $file;
  17720. }
  17721. closedir($handle); 
  17722. ?></PRE
  17723. ></TD
  17724. ></TR
  17725. ></TABLE
  17726. ></DIV
  17727. ></TD
  17728. ></TR
  17729. ></TABLE
  17730. ><P
  17731. >      Arrays are ordered. You can also change the order using various
  17732.      sorting functions. See the <A
  17733. HREF="#ref.array"
  17734. >array
  17735.      functions</A
  17736. > section for more information. You can count
  17737.      the number of items in an array using the
  17738.      <A
  17739. HREF="#function.count"
  17740. ><B
  17741. CLASS="function"
  17742. >count()</B
  17743. ></A
  17744. > function.
  17745.     </P
  17746. ><TABLE
  17747. WIDTH="100%"
  17748. BORDER="0"
  17749. CELLPADDING="0"
  17750. CELLSPACING="0"
  17751. CLASS="EXAMPLE"
  17752. ><TR
  17753. ><TD
  17754. ><DIV
  17755. CLASS="example"
  17756. ><A
  17757. NAME="AEN3208"
  17758. ></A
  17759. ><P
  17760. ><B
  17761. >Example 11-10. Sorting an array</B
  17762. ></P
  17763. ><TABLE
  17764. BORDER="0"
  17765. BGCOLOR="#E0E0E0"
  17766. CELLPADDING="5"
  17767. ><TR
  17768. ><TD
  17769. ><PRE
  17770. CLASS="php"
  17771. ><?php
  17772. sort($files);
  17773. print_r($files);
  17774. ?></PRE
  17775. ></TD
  17776. ></TR
  17777. ></TABLE
  17778. ></DIV
  17779. ></TD
  17780. ></TR
  17781. ></TABLE
  17782. ><P
  17783. >      Because the value of an array can be anything, it can also be
  17784.      another array. This way you can make recursive and
  17785.      multi-dimensional arrays.
  17786.     </P
  17787. ><TABLE
  17788. WIDTH="100%"
  17789. BORDER="0"
  17790. CELLPADDING="0"
  17791. CELLSPACING="0"
  17792. CLASS="EXAMPLE"
  17793. ><TR
  17794. ><TD
  17795. ><DIV
  17796. CLASS="example"
  17797. ><A
  17798. NAME="AEN3212"
  17799. ></A
  17800. ><P
  17801. ><B
  17802. >Example 11-11. Recursive and multi-dimensional arrays</B
  17803. ></P
  17804. ><TABLE
  17805. BORDER="0"
  17806. BGCOLOR="#E0E0E0"
  17807. CELLPADDING="5"
  17808. ><TR
  17809. ><TD
  17810. ><PRE
  17811. CLASS="php"
  17812. ><?php
  17813. $fruits = array ( "fruits"  => array ( "a" => "orange",
  17814.                                        "b" => "banana",
  17815.                                        "c" => "apple"
  17816.                                      ),
  17817.                   "numbers" => array ( 1,
  17818.                                        2,
  17819.                                        3,
  17820.                                        4,
  17821.                                        5,
  17822.                                        6
  17823.                                      ),
  17824.                   "holes"   => array (      "first",
  17825.                                        5 => "second",
  17826.                                             "third"
  17827.                                      )
  17828.                 );
  17829.  
  17830. // Some examples to address values in the array above 
  17831. echo $fruits["holes"][5];    // prints "second"
  17832. echo $fruits["fruits"]["a"]; // prints "orange"
  17833. unset($fruits["holes"][0]);  // remove "first"
  17834.  
  17835. // Create a new multi-dimensional array
  17836. $juices["apple"]["green"] = "good"; 
  17837. ?></PRE
  17838. ></TD
  17839. ></TR
  17840. ></TABLE
  17841. ></DIV
  17842. ></TD
  17843. ></TR
  17844. ></TABLE
  17845. ><P
  17846. >      You should be aware that array assignment always involves
  17847.      value copying. You need to use the reference operator to copy
  17848.      an array by reference.
  17849.      <DIV
  17850. CLASS="informalexample"
  17851. ><P
  17852. ></P
  17853. ><A
  17854. NAME="AEN3216"
  17855. ></A
  17856. ><TABLE
  17857. BORDER="0"
  17858. BGCOLOR="#E0E0E0"
  17859. CELLPADDING="5"
  17860. ><TR
  17861. ><TD
  17862. ><PRE
  17863. CLASS="php"
  17864. ><?php
  17865. $arr1 = array(2, 3);
  17866. $arr2 = $arr1;
  17867. $arr2[] = 4; // $arr2 is changed,
  17868.              // $arr1 is still array(2, 3)
  17869.              
  17870. $arr3 = &$arr1;
  17871. $arr3[] = 4; // now $arr1 and $arr3 are the same
  17872. ?></PRE
  17873. ></TD
  17874. ></TR
  17875. ></TABLE
  17876. ><P
  17877. ></P
  17878. ></DIV
  17879. >
  17880.     </P
  17881. ></DIV
  17882. ></DIV
  17883. ><DIV
  17884. CLASS="sect1"
  17885. ><HR><H2
  17886. CLASS="sect1"
  17887. ><A
  17888. NAME="language.types.object"
  17889. >Objects</A
  17890. ></H2
  17891. ><DIV
  17892. CLASS="sect2"
  17893. ><H3
  17894. CLASS="sect2"
  17895. ><A
  17896. NAME="language.types.object.init"
  17897. >Object Initialization</A
  17898. ></H3
  17899. ><P
  17900. >      To initialize an object, you use the <VAR
  17901. CLASS="literal"
  17902. >new</VAR
  17903. >
  17904.      statement to instantiate the object to a variable.
  17905.  
  17906.      <DIV
  17907. CLASS="informalexample"
  17908. ><P
  17909. ></P
  17910. ><A
  17911. NAME="AEN3224"
  17912. ></A
  17913. ><TABLE
  17914. BORDER="0"
  17915. BGCOLOR="#E0E0E0"
  17916. CELLPADDING="5"
  17917. ><TR
  17918. ><TD
  17919. ><PRE
  17920. CLASS="php"
  17921. ><?php
  17922. class foo
  17923. {
  17924.     function do_foo()
  17925.     {
  17926.         echo "Doing foo."; 
  17927.     }
  17928. }
  17929.  
  17930. $bar = new foo;
  17931. $bar->do_foo();
  17932. ?></PRE
  17933. ></TD
  17934. ></TR
  17935. ></TABLE
  17936. ><P
  17937. ></P
  17938. ></DIV
  17939. >
  17940.     </P
  17941. ><P
  17942. >      For a full discussion, please read the section <A
  17943. HREF="#language.oop"
  17944. >Classes and Objects</A
  17945. >.
  17946.     </P
  17947. ></DIV
  17948. ><DIV
  17949. CLASS="sect2"
  17950. ><HR><H3
  17951. CLASS="sect2"
  17952. ><A
  17953. NAME="language.types.object.casting"
  17954. >Converting to object</A
  17955. ></H3
  17956. ><P
  17957. >      If an object is converted to an object, it is not modified. If a value
  17958.      of any other type is converted to an object, a new instance of the
  17959.      <VAR
  17960. CLASS="literal"
  17961. >stdClass</VAR
  17962. > built in class is created. If the value
  17963.      was null, the new instance will be empty. For any other value, a
  17964.      member variable named <VAR
  17965. CLASS="literal"
  17966. >scalar</VAR
  17967. > will contain the
  17968.      value.
  17969.      <DIV
  17970. CLASS="informalexample"
  17971. ><P
  17972. ></P
  17973. ><A
  17974. NAME="AEN3233"
  17975. ></A
  17976. ><TABLE
  17977. BORDER="0"
  17978. BGCOLOR="#E0E0E0"
  17979. CELLPADDING="5"
  17980. ><TR
  17981. ><TD
  17982. ><PRE
  17983. CLASS="php"
  17984. ><?php
  17985. $obj = (object) 'ciao';
  17986. echo $obj->scalar;  // outputs 'ciao'
  17987. ?></PRE
  17988. ></TD
  17989. ></TR
  17990. ></TABLE
  17991. ><P
  17992. ></P
  17993. ></DIV
  17994. >
  17995.     </P
  17996. ></DIV
  17997. ></DIV
  17998. ><DIV
  17999. CLASS="sect1"
  18000. ><HR><H2
  18001. CLASS="sect1"
  18002. ><A
  18003. NAME="language.types.resource"
  18004. >Resource</A
  18005. ></H2
  18006. ><P
  18007. >      A resource is a special variable, holding
  18008.      a reference to an external resource. Resources
  18009.      are created and used by special functions.
  18010.      See the <A
  18011. HREF="#resource"
  18012. >appendix</A
  18013. > 
  18014.      for a listing of all these
  18015.      functions and the corresponding resource types.
  18016.     </P
  18017. ><DIV
  18018. CLASS="note"
  18019. ><BLOCKQUOTE
  18020. CLASS="note"
  18021. ><P
  18022. ><B
  18023. >Note: </B
  18024. >
  18025.       The resource type was introduced in PHP 4
  18026.      </P
  18027. ></BLOCKQUOTE
  18028. ></DIV
  18029. ><DIV
  18030. CLASS="sect2"
  18031. ><HR><H3
  18032. CLASS="sect2"
  18033. ><A
  18034. NAME="language.types.resource.casting"
  18035. >Converting to resource</A
  18036. ></H3
  18037. ><P
  18038. >      As resource types hold special handlers to opened
  18039.      files, database connections, image canvas areas and
  18040.      the like, you cannot convert any value to a resource.
  18041.     </P
  18042. ></DIV
  18043. ><DIV
  18044. CLASS="sect2"
  18045. ><HR><H3
  18046. CLASS="sect2"
  18047. ><A
  18048. NAME="language.types.resource.self-destruct"
  18049. >Freeing resources</A
  18050. ></H3
  18051. ><P
  18052. >      Due to the reference-counting system introduced
  18053.      with PHP 4's Zend Engine, it is automatically detected
  18054.      when a resource is no longer referred to (just
  18055.      like Java). When this is
  18056.      the case, all resources that were in use for this 
  18057.      resource are made free by the garbage collector.
  18058.      For this reason, it is rarely ever necessary to
  18059.      free the memory manually by using some free_result
  18060.      function.
  18061.      <DIV
  18062. CLASS="note"
  18063. ><BLOCKQUOTE
  18064. CLASS="note"
  18065. ><P
  18066. ><B
  18067. >Note: </B
  18068. >
  18069.        Persistent database links are special, they 
  18070.        are <SPAN
  18071. CLASS="emphasis"
  18072. ><I
  18073. CLASS="emphasis"
  18074. >not</I
  18075. ></SPAN
  18076. > destroyed by the 
  18077.        garbage collector. See also the section about <A
  18078. HREF="#features.persistent-connections"
  18079. >persistent 
  18080.        connections</A
  18081. >.
  18082.       </P
  18083. ></BLOCKQUOTE
  18084. ></DIV
  18085. >
  18086.     </P
  18087. ></DIV
  18088. ></DIV
  18089. ><DIV
  18090. CLASS="sect1"
  18091. ><HR><H2
  18092. CLASS="sect1"
  18093. ><A
  18094. NAME="language.types.null"
  18095. >NULL</A
  18096. ></H2
  18097. ><P
  18098. >     The special <TT
  18099. CLASS="constant"
  18100. ><B
  18101. >NULL</B
  18102. ></TT
  18103. > value represents 
  18104.     that a variable has no value. <TT
  18105. CLASS="constant"
  18106. ><B
  18107. >NULL</B
  18108. ></TT
  18109. > is the only possible value of type
  18110.     <A
  18111. HREF="#language.types.null"
  18112. ><B
  18113. CLASS="type"
  18114. >NULL</B
  18115. ></A
  18116. >.
  18117.    </P
  18118. ><DIV
  18119. CLASS="note"
  18120. ><BLOCKQUOTE
  18121. CLASS="note"
  18122. ><P
  18123. ><B
  18124. >Note: </B
  18125. >
  18126.       The null type was introduced in PHP 4
  18127.      </P
  18128. ></BLOCKQUOTE
  18129. ></DIV
  18130. ><P
  18131. >      A variable is considered to be <TT
  18132. CLASS="constant"
  18133. ><B
  18134. >NULL</B
  18135. ></TT
  18136. > if
  18137.      <P
  18138. ></P
  18139. ><UL
  18140. ><LI
  18141. ><P
  18142. >         it has been assigned the constant <TT
  18143. CLASS="constant"
  18144. ><B
  18145. >NULL</B
  18146. ></TT
  18147. >.
  18148.        </P
  18149. ></LI
  18150. ><LI
  18151. ><P
  18152. >         it has not been set to any value yet.
  18153.        </P
  18154. ></LI
  18155. ><LI
  18156. ><P
  18157. >         it has been <A
  18158. HREF="#function.unset"
  18159. ><B
  18160. CLASS="function"
  18161. >unset()</B
  18162. ></A
  18163. >.
  18164.        </P
  18165. ></LI
  18166. ></UL
  18167. >
  18168.     </P
  18169. ><DIV
  18170. CLASS="sect2"
  18171. ><HR><H3
  18172. CLASS="sect2"
  18173. ><A
  18174. NAME="language.types.null.syntax"
  18175. >Syntax</A
  18176. ></H3
  18177. ><P
  18178. >      There is only one value of type <TT
  18179. CLASS="constant"
  18180. ><B
  18181. >NULL</B
  18182. ></TT
  18183. >, and that is 
  18184.      the case-insensitive keyword <TT
  18185. CLASS="constant"
  18186. ><B
  18187. >NULL</B
  18188. ></TT
  18189. >.
  18190.      <DIV
  18191. CLASS="informalexample"
  18192. ><P
  18193. ></P
  18194. ><A
  18195. NAME="AEN3275"
  18196. ></A
  18197. ><TABLE
  18198. BORDER="0"
  18199. BGCOLOR="#E0E0E0"
  18200. CELLPADDING="5"
  18201. ><TR
  18202. ><TD
  18203. ><PRE
  18204. CLASS="php"
  18205. ><?php
  18206. $var = NULL;       
  18207. ?></PRE
  18208. ></TD
  18209. ></TR
  18210. ></TABLE
  18211. ><P
  18212. ></P
  18213. ></DIV
  18214. >
  18215.     </P
  18216. ><P
  18217. >      See also <A
  18218. HREF="#function.is-null"
  18219. ><B
  18220. CLASS="function"
  18221. >is_null()</B
  18222. ></A
  18223. > and <A
  18224. HREF="#function.unset"
  18225. ><B
  18226. CLASS="function"
  18227. >unset()</B
  18228. ></A
  18229. >.
  18230.     </P
  18231. ></DIV
  18232. ></DIV
  18233. ><DIV
  18234. CLASS="sect1"
  18235. ><HR><H2
  18236. CLASS="sect1"
  18237. ><A
  18238. NAME="language.pseudo-types"
  18239. >Pseudo-types used in this documentation</A
  18240. ></H2
  18241. ><DIV
  18242. CLASS="sect2"
  18243. ><H3
  18244. CLASS="sect2"
  18245. ><A
  18246. NAME="language.types.mixed"
  18247. >mixed</A
  18248. ></H3
  18249. ><P
  18250. >      <VAR
  18251. CLASS="literal"
  18252. >mixed</VAR
  18253. > indicates that a parameter may accept multiple (but not
  18254.      necessarily all) types.
  18255.     </P
  18256. ><P
  18257. >      <A
  18258. HREF="#function.gettype"
  18259. ><B
  18260. CLASS="function"
  18261. >gettype()</B
  18262. ></A
  18263. > for example will accept all PHP types,
  18264.      while <A
  18265. HREF="#function.str-replace"
  18266. ><B
  18267. CLASS="function"
  18268. >str_replace()</B
  18269. ></A
  18270. > will accept strings and arrays.
  18271.     </P
  18272. ></DIV
  18273. ><DIV
  18274. CLASS="sect2"
  18275. ><HR><H3
  18276. CLASS="sect2"
  18277. ><A
  18278. NAME="language.types.number"
  18279. >number</A
  18280. ></H3
  18281. ><P
  18282. >      <VAR
  18283. CLASS="literal"
  18284. >number</VAR
  18285. > indicates that a parameter can be either
  18286.      <A
  18287. HREF="#language.types.integer"
  18288. ><B
  18289. CLASS="type"
  18290. >integer</B
  18291. ></A
  18292. > or <A
  18293. HREF="#language.types.float"
  18294. ><B
  18295. CLASS="type"
  18296. >float</B
  18297. ></A
  18298. >.
  18299.     </P
  18300. ></DIV
  18301. ><DIV
  18302. CLASS="sect2"
  18303. ><HR><H3
  18304. CLASS="sect2"
  18305. ><A
  18306. NAME="language.types.callback"
  18307. >callback</A
  18308. ></H3
  18309. ><P
  18310. >      Some functions like <A
  18311. HREF="#function.call-user-func"
  18312. ><B
  18313. CLASS="function"
  18314. >call_user_func()</B
  18315. ></A
  18316. > 
  18317.      or <A
  18318. HREF="#function.usort"
  18319. ><B
  18320. CLASS="function"
  18321. >usort()</B
  18322. ></A
  18323. > accept user defined 
  18324.      callback functions as a parameter. Callback functions can not only
  18325.      be simple functions but also object methods including static class
  18326.      methods. 
  18327.     </P
  18328. ><P
  18329. >      A PHP function is simply passed by its name as a string. You can
  18330.      pass any builtin or user defined function with the exception of 
  18331.      <A
  18332. HREF="#function.array"
  18333. ><B
  18334. CLASS="function"
  18335. >array()</B
  18336. ></A
  18337. >, 
  18338.      <A
  18339. HREF="#function.echo"
  18340. ><B
  18341. CLASS="function"
  18342. >echo()</B
  18343. ></A
  18344. >, 
  18345.      <A
  18346. HREF="#function.empty"
  18347. ><B
  18348. CLASS="function"
  18349. >empty()</B
  18350. ></A
  18351. >, 
  18352.      <A
  18353. HREF="#function.eval"
  18354. ><B
  18355. CLASS="function"
  18356. >eval()</B
  18357. ></A
  18358. >, 
  18359.      <A
  18360. HREF="#function.exit"
  18361. ><B
  18362. CLASS="function"
  18363. >exit()</B
  18364. ></A
  18365. >, 
  18366.      <A
  18367. HREF="#function.isset"
  18368. ><B
  18369. CLASS="function"
  18370. >isset()</B
  18371. ></A
  18372. >, 
  18373.      <A
  18374. HREF="#function.list"
  18375. ><B
  18376. CLASS="function"
  18377. >list()</B
  18378. ></A
  18379. >, 
  18380.      <A
  18381. HREF="#function.print"
  18382. ><B
  18383. CLASS="function"
  18384. >print()</B
  18385. ></A
  18386. > and 
  18387.      <A
  18388. HREF="#function.unset"
  18389. ><B
  18390. CLASS="function"
  18391. >unset()</B
  18392. ></A
  18393. >.
  18394.     </P
  18395. ><P
  18396. >      A method of an instantiated object is passed as an array containing
  18397.      an object as the element with index 0 and a method name as the 
  18398.      element with index 1.
  18399.     </P
  18400. ><P
  18401. >      Static class methods can also be passed without instantiating an
  18402.      object of that class by passing the class name instead of an 
  18403.      object as the element with index 0.
  18404.     </P
  18405. ><P
  18406. >      <TABLE
  18407. WIDTH="100%"
  18408. BORDER="0"
  18409. CELLPADDING="0"
  18410. CELLSPACING="0"
  18411. CLASS="EXAMPLE"
  18412. ><TR
  18413. ><TD
  18414. ><DIV
  18415. CLASS="example"
  18416. ><A
  18417. NAME="AEN3313"
  18418. ></A
  18419. ><P
  18420. ><B
  18421. >Example 11-12. 
  18422.        Callback function examples
  18423.       </B
  18424. ></P
  18425. ><TABLE
  18426. BORDER="0"
  18427. BGCOLOR="#E0E0E0"
  18428. CELLPADDING="5"
  18429. ><TR
  18430. ><TD
  18431. ><PRE
  18432. CLASS="php"
  18433. ><?php 
  18434. // An example callback function
  18435. function my_callback_function() {
  18436.     echo 'hello world!';
  18437. }
  18438.  
  18439. // An example callback method
  18440. class MyClass {
  18441.     function myCallbackMethod() {
  18442.         echo 'Hello World!';
  18443.     }
  18444. }
  18445.  
  18446. // Type 1: Simple callback
  18447. call_user_func('my_callback_function'); 
  18448.  
  18449. // Type 2: Static class method call
  18450. call_user_func(array('MyClass', 'myCallbackMethod')); 
  18451.  
  18452. // Type 3: Object method call
  18453. $obj = new MyClass();
  18454. call_user_func(array(&$obj, 'myCallbackMethod'));
  18455. ?></PRE
  18456. ></TD
  18457. ></TR
  18458. ></TABLE
  18459. ></DIV
  18460. ></TD
  18461. ></TR
  18462. ></TABLE
  18463. >
  18464.     </P
  18465. ></DIV
  18466. ></DIV
  18467. ><DIV
  18468. CLASS="sect1"
  18469. ><HR><H2
  18470. CLASS="sect1"
  18471. ><A
  18472. NAME="language.types.type-juggling"
  18473. >Type Juggling</A
  18474. ></H2
  18475. ><P
  18476. >     PHP does not require (or support) explicit type definition in
  18477.     variable declaration; a variable's type is determined by the
  18478.     context in which that variable is used. That is to say, if you
  18479.     assign a string value to variable <VAR
  18480. CLASS="parameter"
  18481. >$var</VAR
  18482. >,
  18483.     <VAR
  18484. CLASS="parameter"
  18485. >$var</VAR
  18486. > becomes a string. If you then assign an
  18487.     integer value to <VAR
  18488. CLASS="parameter"
  18489. >$var</VAR
  18490. >, it becomes an
  18491.     integer.
  18492.    </P
  18493. ><P
  18494. >     An example of PHP's automatic type conversion is the addition
  18495.     operator '+'. If any of the operands is a float, then all
  18496.     operands are evaluated as floats, and the result will be a
  18497.     float. Otherwise, the operands will be interpreted as integers,
  18498.     and the result will also be an integer. Note that this does NOT
  18499.     change the types of the operands themselves; the only change is in
  18500.     how the operands are evaluated.
  18501.     <DIV
  18502. CLASS="informalexample"
  18503. ><P
  18504. ></P
  18505. ><A
  18506. NAME="AEN3323"
  18507. ></A
  18508. ><TABLE
  18509. BORDER="0"
  18510. BGCOLOR="#E0E0E0"
  18511. CELLPADDING="5"
  18512. ><TR
  18513. ><TD
  18514. ><PRE
  18515. CLASS="php"
  18516. ><?php
  18517. $foo = "0";  // $foo is string (ASCII 48)
  18518. $foo += 2;   // $foo is now an integer (2)
  18519. $foo = $foo + 1.3;  // $foo is now a float (3.3)
  18520. $foo = 5 + "10 Little Piggies"; // $foo is integer (15)
  18521. $foo = 5 + "10 Small Pigs";     // $foo is integer (15)
  18522. ?></PRE
  18523. ></TD
  18524. ></TR
  18525. ></TABLE
  18526. ><P
  18527. ></P
  18528. ></DIV
  18529. >
  18530.    </P
  18531. ><P
  18532. >     If the last two examples above seem odd, see <A
  18533. HREF="#language.types.string.conversion"
  18534. >String
  18535.     conversion to numbers</A
  18536. >.
  18537.    </P
  18538. ><P
  18539. >     If you wish to force a variable to be evaluated as a certain type,
  18540.     see the section on <A
  18541. HREF="#language.types.typecasting"
  18542. >Type
  18543.     casting</A
  18544. >. If you wish to change the type of a variable, see
  18545.     <A
  18546. HREF="#function.settype"
  18547. ><B
  18548. CLASS="function"
  18549. >settype()</B
  18550. ></A
  18551. >.
  18552.    </P
  18553. ><P
  18554. >     If you would like to test any of the examples in this section, you
  18555.     can use the <A
  18556. HREF="#function.var-dump"
  18557. ><B
  18558. CLASS="function"
  18559. >var_dump()</B
  18560. ></A
  18561. > function.
  18562.    </P
  18563. ><DIV
  18564. CLASS="note"
  18565. ><BLOCKQUOTE
  18566. CLASS="note"
  18567. ><P
  18568. ><B
  18569. >Note: </B
  18570. >
  18571.      The behaviour of an automatic conversion to array is currently
  18572.      undefined.
  18573.     </P
  18574. ><P
  18575. >      <DIV
  18576. CLASS="informalexample"
  18577. ><P
  18578. ></P
  18579. ><A
  18580. NAME="AEN3335"
  18581. ></A
  18582. ><TABLE
  18583. BORDER="0"
  18584. BGCOLOR="#E0E0E0"
  18585. CELLPADDING="5"
  18586. ><TR
  18587. ><TD
  18588. ><PRE
  18589. CLASS="php"
  18590. ><?php
  18591. $a = "1";     // $a is a string
  18592. $a[0] = "f";  // What about string offsets? What happens?
  18593. ?></PRE
  18594. ></TD
  18595. ></TR
  18596. ></TABLE
  18597. ><P
  18598. ></P
  18599. ></DIV
  18600. >
  18601.     </P
  18602. ><P
  18603. >      Since PHP (for historical reasons) supports indexing into strings
  18604.      via offsets using the same syntax as array indexing, the example
  18605.      above leads to a problem: should $a become an array with its first
  18606.      element being "f", or should "f" become the first character of the
  18607.      string $a?
  18608.     </P
  18609. ><P
  18610. >      The current versions of PHP interpret the second assignment as
  18611.      a string offset identification, so $a becomes "f", the result
  18612.      of this automatic conversion however should be considered
  18613.      undefined. PHP 4 introduced the new curly bracket syntax to access
  18614.      characters in string, use this syntax instead of the one presented
  18615.      above: 
  18616.      <DIV
  18617. CLASS="informalexample"
  18618. ><P
  18619. ></P
  18620. ><A
  18621. NAME="AEN3339"
  18622. ></A
  18623. ><TABLE
  18624. BORDER="0"
  18625. BGCOLOR="#E0E0E0"
  18626. CELLPADDING="5"
  18627. ><TR
  18628. ><TD
  18629. ><PRE
  18630. CLASS="php"
  18631. ><?php
  18632. $a    = "abc"; // $a is a string
  18633. $a{1} = "f";   // $a is now "afc"
  18634. ?></PRE
  18635. ></TD
  18636. ></TR
  18637. ></TABLE
  18638. ><P
  18639. ></P
  18640. ></DIV
  18641. >
  18642.      See the section titled <A
  18643. HREF="#language.types.string.substr"
  18644. >String
  18645.      access by character</A
  18646. > for more information.
  18647.     </P
  18648. ></BLOCKQUOTE
  18649. ></DIV
  18650. ><DIV
  18651. CLASS="sect2"
  18652. ><HR><H3
  18653. CLASS="sect2"
  18654. ><A
  18655. NAME="language.types.typecasting"
  18656. >Type Casting</A
  18657. ></H3
  18658. ><P
  18659. >      Type casting in PHP works much as it does in C: the name of the
  18660.      desired type is written in parentheses before the variable which
  18661.      is to be cast.
  18662.      <DIV
  18663. CLASS="informalexample"
  18664. ><P
  18665. ></P
  18666. ><A
  18667. NAME="AEN3345"
  18668. ></A
  18669. ><TABLE
  18670. BORDER="0"
  18671. BGCOLOR="#E0E0E0"
  18672. CELLPADDING="5"
  18673. ><TR
  18674. ><TD
  18675. ><PRE
  18676. CLASS="php"
  18677. ><?php
  18678. $foo = 10;   // $foo is an integer
  18679. $bar = (boolean) $foo;   // $bar is a boolean
  18680. ?></PRE
  18681. ></TD
  18682. ></TR
  18683. ></TABLE
  18684. ><P
  18685. ></P
  18686. ></DIV
  18687. >
  18688.     </P
  18689. ><P
  18690. >      The casts allowed are:
  18691.      <P
  18692. ></P
  18693. ><UL
  18694. ><LI
  18695. ><P
  18696. >(int), (integer) - cast to integer</P
  18697. ></LI
  18698. ><LI
  18699. ><P
  18700. >(bool), (boolean) - cast to boolean</P
  18701. ></LI
  18702. ><LI
  18703. ><P
  18704. >(float), (double), (real) - cast to float</P
  18705. ></LI
  18706. ><LI
  18707. ><P
  18708. >(string) - cast to string</P
  18709. ></LI
  18710. ><LI
  18711. ><P
  18712. >(array) - cast to array</P
  18713. ></LI
  18714. ><LI
  18715. ><P
  18716. >(object) - cast to object</P
  18717. ></LI
  18718. ></UL
  18719. >
  18720.     </P
  18721. ><P
  18722. >      Note that tabs and spaces are allowed inside the parentheses, so
  18723.      the following are functionally equivalent:
  18724.      <DIV
  18725. CLASS="informalexample"
  18726. ><P
  18727. ></P
  18728. ><A
  18729. NAME="AEN3362"
  18730. ></A
  18731. ><TABLE
  18732. BORDER="0"
  18733. BGCOLOR="#E0E0E0"
  18734. CELLPADDING="5"
  18735. ><TR
  18736. ><TD
  18737. ><PRE
  18738. CLASS="php"
  18739. ><?php
  18740. $foo = (int) $bar;
  18741. $foo = ( int ) $bar;
  18742. ?></PRE
  18743. ></TD
  18744. ></TR
  18745. ></TABLE
  18746. ><P
  18747. ></P
  18748. ></DIV
  18749. >
  18750.     </P
  18751. ><DIV
  18752. CLASS="note"
  18753. ><BLOCKQUOTE
  18754. CLASS="note"
  18755. ><P
  18756. ><B
  18757. >Note: </B
  18758. >
  18759.       Instead of casting a variable to string, you can also enclose
  18760.       the variable in double quotes.
  18761.      <DIV
  18762. CLASS="informalexample"
  18763. ><P
  18764. ></P
  18765. ><A
  18766. NAME="AEN3366"
  18767. ></A
  18768. ><TABLE
  18769. BORDER="0"
  18770. BGCOLOR="#E0E0E0"
  18771. CELLPADDING="5"
  18772. ><TR
  18773. ><TD
  18774. ><PRE
  18775. CLASS="php"
  18776. ><?php
  18777. $foo = 10;            // $foo is an integer
  18778. $str = "$foo";        // $str is a string
  18779. $fst = (string) $foo; // $fst is also a string
  18780.  
  18781. // This prints out that "they are the same"
  18782. if ($fst === $str) {
  18783.     echo "they are the same";
  18784. }
  18785. ?></PRE
  18786. ></TD
  18787. ></TR
  18788. ></TABLE
  18789. ><P
  18790. ></P
  18791. ></DIV
  18792. >
  18793.      </P
  18794. ></BLOCKQUOTE
  18795. ></DIV
  18796. ><P
  18797. >      It may not be obvious exactly what will happen when casting
  18798.      between certain types. For more info, see these sections:
  18799.     
  18800.      <P
  18801. ></P
  18802. ><UL
  18803. ><LI
  18804. ><P
  18805. ><A
  18806. HREF="#language.types.boolean.casting"
  18807. >Converting to 
  18808.         boolean</A
  18809. ></P
  18810. ></LI
  18811. ><LI
  18812. ><P
  18813. ><A
  18814. HREF="#language.types.integer.casting"
  18815. >Converting to 
  18816.         integer</A
  18817. ></P
  18818. ></LI
  18819. ><LI
  18820. ><P
  18821. ><A
  18822. HREF="#language.types.float.casting"
  18823. >Converting to 
  18824.         float</A
  18825. ></P
  18826. ></LI
  18827. ><LI
  18828. ><P
  18829. ><A
  18830. HREF="#language.types.string.casting"
  18831. >Converting to 
  18832.         string</A
  18833. ></P
  18834. ></LI
  18835. ><LI
  18836. ><P
  18837. ><A
  18838. HREF="#language.types.array.casting"
  18839. >Converting to 
  18840.         array</A
  18841. ></P
  18842. ></LI
  18843. ><LI
  18844. ><P
  18845. ><A
  18846. HREF="#language.types.object.casting"
  18847. >Converting to 
  18848.         object</A
  18849. ></P
  18850. ></LI
  18851. ><LI
  18852. ><P
  18853. ><A
  18854. HREF="#language.types.resource.casting"
  18855. >Converting to 
  18856.         resource</A
  18857. ></P
  18858. ></LI
  18859. ><LI
  18860. ><P
  18861. >         <A
  18862. HREF="#types.comparisons"
  18863. >The type comparison tables</A
  18864. >
  18865.        </P
  18866. ></LI
  18867. ></UL
  18868. >
  18869.     </P
  18870. ></DIV
  18871. ></DIV
  18872. ></DIV
  18873. ><DIV
  18874. CLASS="chapter"
  18875. ><HR><H1
  18876. ><A
  18877. NAME="language.variables"
  18878. >Chapter 12. Variables</A
  18879. ></H1
  18880. ><DIV
  18881. CLASS="sect1"
  18882. ><H2
  18883. CLASS="sect1"
  18884. ><A
  18885. NAME="language.variables.basics"
  18886. >Basics</A
  18887. ></H2
  18888. ><P
  18889. >     Variables in PHP are represented by a dollar sign followed by the
  18890.     name of the variable. The variable name is case-sensitive.
  18891.    </P
  18892. ><P
  18893. >     Variable names follow the same rules as other labels in PHP. A
  18894.     valid variable name starts with a letter or underscore, followed
  18895.     by any number of letters, numbers, or underscores. As a regular
  18896.     expression, it would be expressed thus:
  18897.     '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
  18898.    </P
  18899. ><DIV
  18900. CLASS="note"
  18901. ><BLOCKQUOTE
  18902. CLASS="note"
  18903. ><P
  18904. ><B
  18905. >Note: </B
  18906. >
  18907.      For our purposes here, a letter is a-z, A-Z, and the ASCII
  18908.      characters from 127 through 255 (0x7f-0xff).
  18909.     </P
  18910. ></BLOCKQUOTE
  18911. ></DIV
  18912. ><P
  18913. >     For information on variable related functions, see the
  18914.     <A
  18915. HREF="#ref.var"
  18916. >Variable Functions Reference</A
  18917. >.
  18918.    </P
  18919. ><P
  18920. >     <DIV
  18921. CLASS="informalexample"
  18922. ><P
  18923. ></P
  18924. ><A
  18925. NAME="AEN3405"
  18926. ></A
  18927. ><TABLE
  18928. BORDER="0"
  18929. BGCOLOR="#E0E0E0"
  18930. CELLPADDING="5"
  18931. ><TR
  18932. ><TD
  18933. ><PRE
  18934. CLASS="php"
  18935. ><?php
  18936. $var = "Bob";
  18937. $Var = "Joe";
  18938. echo "$var, $Var";      // outputs "Bob, Joe"
  18939.  
  18940. $4site = 'not yet';     // invalid; starts with a number
  18941. $_4site = 'not yet';    // valid; starts with an underscore
  18942. $t├ñyte = 'mansikka';    // valid; '├ñ' is (Extended) ASCII 228.
  18943. ?></PRE
  18944. ></TD
  18945. ></TR
  18946. ></TABLE
  18947. ><P
  18948. ></P
  18949. ></DIV
  18950. >
  18951.    </P
  18952. ><P
  18953. >     In PHP 3, variables are always assigned by value. That is to say,
  18954.     when you assign an expression to a variable, the entire value of
  18955.     the original expression is copied into the destination
  18956.     variable. This means, for instance, that after assigning one
  18957.     variable's value to another, changing one of those variables will
  18958.     have no effect on the other. For more information on this kind of
  18959.     assignment, see the chapter on <A
  18960. HREF="#language.expressions"
  18961. >Expressions</A
  18962. >.
  18963.    </P
  18964. ><P
  18965. >     As of PHP 4, PHP offers another way to assign values to variables:
  18966.     <A
  18967. HREF="#language.references"
  18968. >assign by reference</A
  18969. >. 
  18970.     This means that the new variable simply references (in other words, 
  18971.     "becomes an alias for" or "points to") the original variable. 
  18972.     Changes to the new variable affect the original, and vice versa. 
  18973.     This also means that no copying is performed; thus, the assignment 
  18974.     happens more quickly. However, any speedup will likely be noticed 
  18975.     only in tight loops or when assigning large 
  18976.     <A
  18977. HREF="#language.types.array"
  18978. >arrays</A
  18979. > or 
  18980.     <A
  18981. HREF="#language.types.object"
  18982. >objects</A
  18983. >.
  18984.    </P
  18985. ><P
  18986. >     To assign by reference, simply prepend an ampersand (&) to the
  18987.     beginning of the variable which is being assigned (the source
  18988.     variable). For instance, the following code snippet outputs 'My
  18989.     name is Bob' twice:
  18990.  
  18991.     <DIV
  18992. CLASS="informalexample"
  18993. ><P
  18994. ></P
  18995. ><A
  18996. NAME="AEN3414"
  18997. ></A
  18998. ><TABLE
  18999. BORDER="0"
  19000. BGCOLOR="#E0E0E0"
  19001. CELLPADDING="5"
  19002. ><TR
  19003. ><TD
  19004. ><PRE
  19005. CLASS="php"
  19006. ><?php
  19007. $foo = 'Bob';              // Assign the value 'Bob' to $foo
  19008. $bar = &$foo;              // Reference $foo via $bar.
  19009. $bar = "My name is $bar";  // Alter $bar...
  19010. echo $bar;
  19011. echo $foo;                 // $foo is altered too.
  19012. ?></PRE
  19013. ></TD
  19014. ></TR
  19015. ></TABLE
  19016. ><P
  19017. ></P
  19018. ></DIV
  19019. >
  19020.    </P
  19021. ><P
  19022. >     One important thing to note is that only named variables may be
  19023.     assigned by reference.
  19024.     <DIV
  19025. CLASS="informalexample"
  19026. ><P
  19027. ></P
  19028. ><A
  19029. NAME="AEN3417"
  19030. ></A
  19031. ><TABLE
  19032. BORDER="0"
  19033. BGCOLOR="#E0E0E0"
  19034. CELLPADDING="5"
  19035. ><TR
  19036. ><TD
  19037. ><PRE
  19038. CLASS="php"
  19039. ><?php
  19040. $foo = 25;
  19041. $bar = &$foo;      // This is a valid assignment.
  19042. $bar = &(24 * 7);  // Invalid; references an unnamed expression.
  19043.  
  19044. function test()
  19045. {
  19046.    return 25;
  19047. }
  19048.  
  19049. $bar = &test();    // Invalid.
  19050. ?></PRE
  19051. ></TD
  19052. ></TR
  19053. ></TABLE
  19054. ><P
  19055. ></P
  19056. ></DIV
  19057. >
  19058.    </P
  19059. ></DIV
  19060. ><DIV
  19061. CLASS="sect1"
  19062. ><HR><H2
  19063. CLASS="sect1"
  19064. ><A
  19065. NAME="language.variables.predefined"
  19066. >Predefined variables</A
  19067. ></H2
  19068. ><P
  19069. >     PHP provides a large number of predefined variables to any script
  19070.     which it runs. Many of these variables, however, cannot be fully
  19071.     documented as they are dependent upon which server is running, the
  19072.     version and setup of the server, and other factors. Some of these
  19073.     variables will not be available when PHP is run on the 
  19074.     <A
  19075. HREF="#features.commandline"
  19076. >command line</A
  19077. >. 
  19078.     For a listing of these variables, please see the section on 
  19079.     <A
  19080. HREF="#reserved.variables"
  19081. >Reserved Predefined Variables</A
  19082. >.
  19083.    </P
  19084. ><DIV
  19085. CLASS="warning"
  19086. ><P
  19087. ></P
  19088. ><TABLE
  19089. CLASS="warning"
  19090. BORDER="1"
  19091. WIDTH="100%"
  19092. ><TR
  19093. ><TD
  19094. ALIGN="CENTER"
  19095. ><B
  19096. >Warning</B
  19097. ></TD
  19098. ></TR
  19099. ><TR
  19100. ><TD
  19101. ALIGN="LEFT"
  19102. ><P
  19103. >      In PHP 4.2.0 and later, the default value for the PHP directive <A
  19104. HREF="#ini.register-globals"
  19105. >register_globals</A
  19106. > is 
  19107.      <SPAN
  19108. CLASS="emphasis"
  19109. ><I
  19110. CLASS="emphasis"
  19111. >off</I
  19112. ></SPAN
  19113. >. This is a major change in PHP.  Having 
  19114.      register_globals <SPAN
  19115. CLASS="emphasis"
  19116. ><I
  19117. CLASS="emphasis"
  19118. >off</I
  19119. ></SPAN
  19120. > affects the set of predefined 
  19121.      variables available in the global scope.  For example, to get 
  19122.      <VAR
  19123. CLASS="varname"
  19124. >DOCUMENT_ROOT</VAR
  19125. > you'll use 
  19126.      <VAR
  19127. CLASS="varname"
  19128. >$_SERVER['DOCUMENT_ROOT']</VAR
  19129. > instead of 
  19130.      <VAR
  19131. CLASS="varname"
  19132. >$DOCUMENT_ROOT</VAR
  19133. >, or <VAR
  19134. CLASS="varname"
  19135. >$_GET['id']</VAR
  19136. > from 
  19137.      the URL <VAR
  19138. CLASS="literal"
  19139. >http://www.example.com/test.php?id=3</VAR
  19140. > instead 
  19141.      of <VAR
  19142. CLASS="varname"
  19143. >$id</VAR
  19144. >, or <VAR
  19145. CLASS="varname"
  19146. >$_ENV['HOME']</VAR
  19147. > instead of 
  19148.      <VAR
  19149. CLASS="varname"
  19150. >$HOME</VAR
  19151. >.
  19152.     </P
  19153. ><P
  19154. >      For related information on this change, read the configuration entry for 
  19155.      <A
  19156. HREF="#ini.register-globals"
  19157. >register_globals</A
  19158. >, the security 
  19159.      chapter on <A
  19160. HREF="#security.globals"
  19161. >Using Register Globals
  19162.      </A
  19163. >, as well as the PHP <A
  19164. HREF="http://www.php.net/release_4_1_0.php"
  19165. TARGET="_top"
  19166. >4.1.0
  19167.      </A
  19168. > and <A
  19169. HREF="http://www.php.net/release_4_2_0.php"
  19170. TARGET="_top"
  19171. >4.2.0</A
  19172. > Release 
  19173.      Announcements.
  19174.     </P
  19175. ><P
  19176. >      Using the available PHP Reserved Predefined Variables, like the 
  19177.      <A
  19178. HREF="#language.variables.superglobals"
  19179. >superglobal arrays</A
  19180. >, 
  19181.      is preferred.
  19182.     </P
  19183. ></TD
  19184. ></TR
  19185. ></TABLE
  19186. ></DIV
  19187. ><P
  19188. >     From version 4.1.0 onward, PHP provides an additional set of predefined arrays
  19189.     containing variables from the web server (if applicable), the
  19190.     environment, and user input. These new arrays are rather special
  19191.     in that they are automatically global--i.e., automatically
  19192.     available in every scope. For this reason, they are often known as
  19193.     'autoglobals' or 'superglobals'. (There is no mechanism in PHP for
  19194.     user-defined superglobals.) The superglobals are listed below;
  19195.     however, for a listing of their contents and further discussion on
  19196.     PHP predefined variables and their natures, please see the section
  19197.     <A
  19198. HREF="#reserved.variables"
  19199. >Reserved Predefined Variables</A
  19200. >.  
  19201.     Also, you'll notice how the older predefined variables 
  19202.     (<VAR
  19203. CLASS="varname"
  19204. >$HTTP_*_VARS</VAR
  19205. >) still exist.
  19206.  
  19207.     As of PHP 5.0.0, the long PHP 
  19208. <A
  19209. HREF="#language.variables.predefined"
  19210. >predefined variable</A
  19211. >
  19212. arrays may be disabled with the 
  19213. <A
  19214. HREF="#ini.register-long-arrays"
  19215. >register_long_arrays</A
  19216. >
  19217. directive.
  19218.    </P
  19219. ><DIV
  19220. CLASS="note"
  19221. ><BLOCKQUOTE
  19222. CLASS="note"
  19223. ><P
  19224. ><B
  19225. >Variable variables: </B
  19226. >
  19227.      Superglobals cannot be used as 
  19228.      <A
  19229. HREF="#language.variables.variable"
  19230. >variable variables</A
  19231. >
  19232.      inside functions or class methods.
  19233.     </P
  19234. ></BLOCKQUOTE
  19235. ></DIV
  19236. ><DIV
  19237. CLASS="note"
  19238. ><BLOCKQUOTE
  19239. CLASS="note"
  19240. ><P
  19241. ><B
  19242. >Note: </B
  19243. >
  19244.      Even though both the superglobal and HTTP_*_VARS can exist at the same
  19245.      time; they are not identical, so modifying one will not change the other.
  19246.     </P
  19247. ></BLOCKQUOTE
  19248. ></DIV
  19249. ><P
  19250. >     If certain variables in <A
  19251. HREF="#ini.variables-order"
  19252. >variables_order</A
  19253. > are not set, their
  19254.     appropriate PHP predefined arrays are also left empty.
  19255.    </P
  19256. ><P
  19257. ></P
  19258. ><DIV
  19259. CLASS="variablelist"
  19260. ><P
  19261. ><B
  19262. >PHP Superglobals</B
  19263. ></P
  19264. ><DL
  19265. ><DT
  19266. ><A
  19267. HREF="#reserved.variables.globals"
  19268. >$GLOBALS</A
  19269. ></DT
  19270. ><DD
  19271. ><P
  19272. >        Contains a reference to every variable which is currently
  19273.        available within the global scope of the script. The keys of
  19274.        this array are the names of the global variables.
  19275.        <VAR
  19276. CLASS="varname"
  19277. >$GLOBALS</VAR
  19278. > has existed since PHP 3.
  19279.       </P
  19280. ></DD
  19281. ><DT
  19282. ><A
  19283. HREF="#reserved.variables.server"
  19284. >$_SERVER</A
  19285. ></DT
  19286. ><DD
  19287. ><P
  19288. >        Variables set by the web server or otherwise directly related
  19289.        to the execution environment of the current script. Analogous
  19290.        to the old <VAR
  19291. CLASS="varname"
  19292. >$HTTP_SERVER_VARS</VAR
  19293. > array (which is
  19294.        still available, but deprecated).
  19295.       </P
  19296. ></DD
  19297. ><DT
  19298. ><A
  19299. HREF="#reserved.variables.get"
  19300. >$_GET</A
  19301. ></DT
  19302. ><DD
  19303. ><P
  19304. >        Variables provided to the script via HTTP GET. Analogous to the
  19305.        old <VAR
  19306. CLASS="varname"
  19307. >$HTTP_GET_VARS</VAR
  19308. > array (which is still
  19309.        available, but deprecated).
  19310.       </P
  19311. ></DD
  19312. ><DT
  19313. ><A
  19314. HREF="#reserved.variables.post"
  19315. >$_POST</A
  19316. ></DT
  19317. ><DD
  19318. ><P
  19319. >        Variables provided to the script via HTTP POST. Analogous to the
  19320.        old <VAR
  19321. CLASS="varname"
  19322. >$HTTP_POST_VARS</VAR
  19323. > array (which is still
  19324.        available, but deprecated).
  19325.       </P
  19326. ></DD
  19327. ><DT
  19328. ><A
  19329. HREF="#reserved.variables.cookies"
  19330. >$_COOKIE</A
  19331. ></DT
  19332. ><DD
  19333. ><P
  19334. >        Variables provided to the script via HTTP cookies. Analogous to
  19335.        the old <VAR
  19336. CLASS="varname"
  19337. >$HTTP_COOKIE_VARS</VAR
  19338. > array (which is
  19339.        still available, but deprecated).
  19340.       </P
  19341. ></DD
  19342. ><DT
  19343. ><A
  19344. HREF="#reserved.variables.files"
  19345. >$_FILES</A
  19346. ></DT
  19347. ><DD
  19348. ><P
  19349. >        Variables provided to the script via HTTP post file
  19350.        uploads. Analogous to the old
  19351.        <VAR
  19352. CLASS="varname"
  19353. >$HTTP_POST_FILES</VAR
  19354. > array (which is still
  19355.        available, but deprecated). See <A
  19356. HREF="#features.file-upload.post-method"
  19357. >POST method
  19358.         uploads</A
  19359. > for more information.
  19360.       </P
  19361. ></DD
  19362. ><DT
  19363. ><A
  19364. HREF="#reserved.variables.environment"
  19365. >$_ENV</A
  19366. ></DT
  19367. ><DD
  19368. ><P
  19369. >        Variables provided to the script via the environment. Analogous
  19370.        to the old <VAR
  19371. CLASS="varname"
  19372. >$HTTP_ENV_VARS</VAR
  19373. > array (which is
  19374.        still available, but deprecated).
  19375.       </P
  19376. ></DD
  19377. ><DT
  19378. ><A
  19379. HREF="#reserved.variables.request"
  19380. >$_REQUEST</A
  19381. ></DT
  19382. ><DD
  19383. ><P
  19384. >        Variables provided to the script via the GET, POST, and COOKIE input
  19385.        mechanisms, and which therefore cannot be trusted. The presence and
  19386.        order of variable inclusion in this array is defined according to the
  19387.        PHP <A
  19388. HREF="#ini.variables-order"
  19389. >variables_order</A
  19390. >
  19391.        configuration directive. This array has no direct analogue in versions
  19392.        of PHP prior to 4.1.0.  See also 
  19393.        <A
  19394. HREF="#function.import-request-variables"
  19395. ><B
  19396. CLASS="function"
  19397. >import_request_variables()</B
  19398. ></A
  19399. >.
  19400.       </P
  19401. ><DIV
  19402. CLASS="caution"
  19403. ><P
  19404. ></P
  19405. ><TABLE
  19406. CLASS="caution"
  19407. BORDER="1"
  19408. WIDTH="100%"
  19409. ><TR
  19410. ><TD
  19411. ALIGN="CENTER"
  19412. ><B
  19413. >Caution</B
  19414. ></TD
  19415. ></TR
  19416. ><TR
  19417. ><TD
  19418. ALIGN="LEFT"
  19419. ><P
  19420. >         Since PHP 4.3.0, FILE information from <VAR
  19421. CLASS="varname"
  19422. >$_FILES</VAR
  19423. > does
  19424.         not exist in <VAR
  19425. CLASS="varname"
  19426. >$_REQUEST</VAR
  19427. >.
  19428.        </P
  19429. ></TD
  19430. ></TR
  19431. ></TABLE
  19432. ></DIV
  19433. ><DIV
  19434. CLASS="note"
  19435. ><BLOCKQUOTE
  19436. CLASS="note"
  19437. ><P
  19438. ><B
  19439. >Note: </B
  19440. >
  19441.         When running on the <A
  19442. HREF="#features.commandline"
  19443. >command line
  19444.         </A
  19445. >, this will <SPAN
  19446. CLASS="emphasis"
  19447. ><I
  19448. CLASS="emphasis"
  19449. >not</I
  19450. ></SPAN
  19451. > include the 
  19452.         <VAR
  19453. CLASS="varname"
  19454. >argv</VAR
  19455. > and <VAR
  19456. CLASS="varname"
  19457. >argc</VAR
  19458. > entries; these are 
  19459.         present in the <VAR
  19460. CLASS="varname"
  19461. >$_SERVER</VAR
  19462. > array.
  19463.        </P
  19464. ></BLOCKQUOTE
  19465. ></DIV
  19466. ></DD
  19467. ><DT
  19468. ><A
  19469. HREF="#reserved.variables.session"
  19470. >$_SESSION</A
  19471. ></DT
  19472. ><DD
  19473. ><P
  19474. >        Variables which are currently registered to a script's
  19475.        session. Analogous to the old
  19476.        <VAR
  19477. CLASS="varname"
  19478. >$HTTP_SESSION_VARS</VAR
  19479. > array (which is still
  19480.        available, but deprecated). See the <A
  19481. HREF="#ref.session"
  19482. >Session handling functions</A
  19483. > section
  19484.        for more information.
  19485.       </P
  19486. ></DD
  19487. ></DL
  19488. ></DIV
  19489. ></DIV
  19490. ><DIV
  19491. CLASS="sect1"
  19492. ><HR><H2
  19493. CLASS="sect1"
  19494. ><A
  19495. NAME="language.variables.scope"
  19496. >Variable scope</A
  19497. ></H2
  19498. ><P
  19499. >     The scope of a variable is the context within which it is defined.
  19500.     For the most part all PHP variables only have a single scope.
  19501.     This single scope spans included and required files as well.  For
  19502.     example:
  19503.    </P
  19504. ><DIV
  19505. CLASS="informalexample"
  19506. ><P
  19507. ></P
  19508. ><A
  19509. NAME="AEN3530"
  19510. ></A
  19511. ><TABLE
  19512. BORDER="0"
  19513. BGCOLOR="#E0E0E0"
  19514. CELLPADDING="5"
  19515. ><TR
  19516. ><TD
  19517. ><PRE
  19518. CLASS="php"
  19519. ><?php
  19520. $a = 1;
  19521. include "b.inc";
  19522. ?></PRE
  19523. ></TD
  19524. ></TR
  19525. ></TABLE
  19526. ><P
  19527. ></P
  19528. ></DIV
  19529. ><P
  19530. >     Here the <VAR
  19531. CLASS="varname"
  19532. >$a</VAR
  19533. > variable will be available within
  19534.     the included <TT
  19535. CLASS="filename"
  19536. >b.inc</TT
  19537. > script.  However, within
  19538.     user-defined functions a local function scope is introduced.  Any
  19539.     variable used inside a function is by default limited to the local
  19540.     function scope.  For example:
  19541.    </P
  19542. ><DIV
  19543. CLASS="informalexample"
  19544. ><P
  19545. ></P
  19546. ><A
  19547. NAME="AEN3535"
  19548. ></A
  19549. ><TABLE
  19550. BORDER="0"
  19551. BGCOLOR="#E0E0E0"
  19552. CELLPADDING="5"
  19553. ><TR
  19554. ><TD
  19555. ><PRE
  19556. CLASS="php"
  19557. ><?php
  19558. $a = 1; /* global scope */ 
  19559.  
  19560. function Test()
  19561. { 
  19562.     echo $a; /* reference to local scope variable */ 
  19563. } 
  19564.  
  19565. Test();
  19566. ?></PRE
  19567. ></TD
  19568. ></TR
  19569. ></TABLE
  19570. ><P
  19571. ></P
  19572. ></DIV
  19573. ><P
  19574. >     This script will not produce any output because the echo statement
  19575.     refers to a local version of the <VAR
  19576. CLASS="varname"
  19577. >$a</VAR
  19578. > variable,
  19579.     and it has not been assigned a value within this scope.  You may
  19580.     notice that this is a little bit different from the C language in
  19581.     that global variables in C are automatically available to
  19582.     functions unless specifically overridden by a local definition.
  19583.     This can cause some problems in that people may inadvertently
  19584.     change a global variable.  In PHP global variables must be
  19585.     declared global inside a function if they are going to be used in
  19586.     that function.
  19587.    </P
  19588. ><DIV
  19589. CLASS="sect2"
  19590. ><HR><H3
  19591. CLASS="sect2"
  19592. ><A
  19593. NAME="language.variables.scope.global"
  19594. >The global keyword</A
  19595. ></H3
  19596. ><P
  19597. >      First, an example use of <VAR
  19598. CLASS="literal"
  19599. >global</VAR
  19600. >:
  19601.     </P
  19602. ><P
  19603. >      <TABLE
  19604. WIDTH="100%"
  19605. BORDER="0"
  19606. CELLPADDING="0"
  19607. CELLSPACING="0"
  19608. CLASS="EXAMPLE"
  19609. ><TR
  19610. ><TD
  19611. ><DIV
  19612. CLASS="example"
  19613. ><A
  19614. NAME="AEN3544"
  19615. ></A
  19616. ><P
  19617. ><B
  19618. >Example 12-1. Using global</B
  19619. ></P
  19620. ><TABLE
  19621. BORDER="0"
  19622. BGCOLOR="#E0E0E0"
  19623. CELLPADDING="5"
  19624. ><TR
  19625. ><TD
  19626. ><PRE
  19627. CLASS="php"
  19628. ><?php
  19629. $a = 1;
  19630. $b = 2;
  19631.  
  19632. function Sum()
  19633. {
  19634.     global $a, $b;
  19635.  
  19636.     $b = $a + $b;
  19637. } 
  19638.  
  19639. Sum();
  19640. echo $b;
  19641. ?></PRE
  19642. ></TD
  19643. ></TR
  19644. ></TABLE
  19645. ></DIV
  19646. ></TD
  19647. ></TR
  19648. ></TABLE
  19649. >
  19650.     </P
  19651. ><P
  19652. >     The above script will output "3".  By declaring
  19653.     <VAR
  19654. CLASS="varname"
  19655. >$a</VAR
  19656. > and <VAR
  19657. CLASS="varname"
  19658. >$b</VAR
  19659. > global within the
  19660.     function, all references to either variable will refer to the
  19661.     global version.  There is no limit to the number of global
  19662.     variables that can be manipulated by a function.
  19663.    </P
  19664. ><P
  19665. >     A second way to access variables from the global scope is to use
  19666.     the special PHP-defined <VAR
  19667. CLASS="varname"
  19668. >$GLOBALS</VAR
  19669. > array.  The
  19670.     previous example can be rewritten as:
  19671.    </P
  19672. ><P
  19673. >     <TABLE
  19674. WIDTH="100%"
  19675. BORDER="0"
  19676. CELLPADDING="0"
  19677. CELLSPACING="0"
  19678. CLASS="EXAMPLE"
  19679. ><TR
  19680. ><TD
  19681. ><DIV
  19682. CLASS="example"
  19683. ><A
  19684. NAME="AEN3553"
  19685. ></A
  19686. ><P
  19687. ><B
  19688. >Example 12-2. Using <VAR
  19689. CLASS="varname"
  19690. >$GLOBALS</VAR
  19691. > instead of global</B
  19692. ></P
  19693. ><TABLE
  19694. BORDER="0"
  19695. BGCOLOR="#E0E0E0"
  19696. CELLPADDING="5"
  19697. ><TR
  19698. ><TD
  19699. ><PRE
  19700. CLASS="php"
  19701. ><?php
  19702. $a = 1;
  19703. $b = 2;
  19704.  
  19705. function Sum()
  19706. {
  19707.     $GLOBALS["b"] = $GLOBALS["a"] + $GLOBALS["b"];
  19708. } 
  19709.  
  19710. Sum();
  19711. echo $b;
  19712. ?></PRE
  19713. ></TD
  19714. ></TR
  19715. ></TABLE
  19716. ></DIV
  19717. ></TD
  19718. ></TR
  19719. ></TABLE
  19720. >
  19721.    </P
  19722. ><P
  19723. >     The <VAR
  19724. CLASS="varname"
  19725. >$GLOBALS</VAR
  19726. > array is an associative array with
  19727.     the name of the global variable being the key and the contents of
  19728.     that variable being the value of the array element.
  19729.     Notice how <VAR
  19730. CLASS="varname"
  19731. >$GLOBALS</VAR
  19732. > exists in any scope, this 
  19733.     is because $GLOBALS is a <A
  19734. HREF="#language.variables.superglobals"
  19735. >superglobal</A
  19736. >.
  19737.     Here's an example demonstrating the power of superglobals: 
  19738.    </P
  19739. ><P
  19740. >     <TABLE
  19741. WIDTH="100%"
  19742. BORDER="0"
  19743. CELLPADDING="0"
  19744. CELLSPACING="0"
  19745. CLASS="EXAMPLE"
  19746. ><TR
  19747. ><TD
  19748. ><DIV
  19749. CLASS="example"
  19750. ><A
  19751. NAME="AEN3562"
  19752. ></A
  19753. ><P
  19754. ><B
  19755. >Example 12-3. Example demonstrating superglobals and scope</B
  19756. ></P
  19757. ><TABLE
  19758. BORDER="0"
  19759. BGCOLOR="#E0E0E0"
  19760. CELLPADDING="5"
  19761. ><TR
  19762. ><TD
  19763. ><PRE
  19764. CLASS="php"
  19765. ><?php
  19766. function test_global()
  19767. {
  19768.     // Most predefined variables aren't "super" and require 
  19769.     // 'global' to be available to the functions local scope.
  19770.     global $HTTP_POST_VARS;
  19771.     
  19772.     echo $HTTP_POST_VARS['name'];
  19773.     
  19774.     // Superglobals are available in any scope and do 
  19775.     // not require 'global'. Superglobals are available 
  19776.     // as of PHP 4.1.0
  19777.     echo $_POST['name'];
  19778. }
  19779. ?></PRE
  19780. ></TD
  19781. ></TR
  19782. ></TABLE
  19783. ></DIV
  19784. ></TD
  19785. ></TR
  19786. ></TABLE
  19787. >
  19788.    </P
  19789. ></DIV
  19790. ><DIV
  19791. CLASS="sect2"
  19792. ><HR><H3
  19793. CLASS="sect2"
  19794. ><A
  19795. NAME="language.variables.scope.static"
  19796. >Using static variables</A
  19797. ></H3
  19798. ><P
  19799. >     Another important feature of variable scoping is the
  19800.     <SPAN
  19801. CLASS="emphasis"
  19802. ><I
  19803. CLASS="emphasis"
  19804. >static</I
  19805. ></SPAN
  19806. > variable.  A static variable exists
  19807.     only in a local function scope, but it does not lose its value
  19808.     when program execution leaves this scope.  Consider the following
  19809.     example:
  19810.    </P
  19811. ><P
  19812. >     <TABLE
  19813. WIDTH="100%"
  19814. BORDER="0"
  19815. CELLPADDING="0"
  19816. CELLSPACING="0"
  19817. CLASS="EXAMPLE"
  19818. ><TR
  19819. ><TD
  19820. ><DIV
  19821. CLASS="example"
  19822. ><A
  19823. NAME="AEN3570"
  19824. ></A
  19825. ><P
  19826. ><B
  19827. >Example 12-4. Example demonstrating need for static variables</B
  19828. ></P
  19829. ><TABLE
  19830. BORDER="0"
  19831. BGCOLOR="#E0E0E0"
  19832. CELLPADDING="5"
  19833. ><TR
  19834. ><TD
  19835. ><PRE
  19836. CLASS="php"
  19837. ><?php
  19838. function Test ()
  19839. {
  19840.     $a = 0;
  19841.     echo $a;
  19842.     $a++;
  19843. }
  19844. ?></PRE
  19845. ></TD
  19846. ></TR
  19847. ></TABLE
  19848. ></DIV
  19849. ></TD
  19850. ></TR
  19851. ></TABLE
  19852. >
  19853.    </P
  19854. ><P
  19855. >     This function is quite useless since every time it is called it
  19856.     sets <VAR
  19857. CLASS="varname"
  19858. >$a</VAR
  19859. > to <VAR
  19860. CLASS="literal"
  19861. >0</VAR
  19862. > and prints
  19863.     "0".  The <VAR
  19864. CLASS="varname"
  19865. >$a</VAR
  19866. >++ which increments the
  19867.     variable serves no purpose since as soon as the function exits the
  19868.     <VAR
  19869. CLASS="varname"
  19870. >$a</VAR
  19871. > variable disappears.  To make a useful
  19872.     counting function which will not lose track of the current count,
  19873.     the <VAR
  19874. CLASS="varname"
  19875. >$a</VAR
  19876. > variable is declared static:
  19877.    </P
  19878. ><P
  19879. >     <TABLE
  19880. WIDTH="100%"
  19881. BORDER="0"
  19882. CELLPADDING="0"
  19883. CELLSPACING="0"
  19884. CLASS="EXAMPLE"
  19885. ><TR
  19886. ><TD
  19887. ><DIV
  19888. CLASS="example"
  19889. ><A
  19890. NAME="AEN3580"
  19891. ></A
  19892. ><P
  19893. ><B
  19894. >Example 12-5. Example use of static variables</B
  19895. ></P
  19896. ><TABLE
  19897. BORDER="0"
  19898. BGCOLOR="#E0E0E0"
  19899. CELLPADDING="5"
  19900. ><TR
  19901. ><TD
  19902. ><PRE
  19903. CLASS="php"
  19904. ><?php
  19905. function Test()
  19906. {
  19907.     static $a = 0;
  19908.     echo $a;
  19909.     $a++;
  19910. }
  19911. ?></PRE
  19912. ></TD
  19913. ></TR
  19914. ></TABLE
  19915. ></DIV
  19916. ></TD
  19917. ></TR
  19918. ></TABLE
  19919. >
  19920.    </P
  19921. ><P
  19922. >     Now, every time the Test() function is called it will print the
  19923.     value of <VAR
  19924. CLASS="varname"
  19925. >$a</VAR
  19926. > and increment it.
  19927.    </P
  19928. ><P
  19929. >     Static variables also provide one way to deal with recursive
  19930.     functions. A recursive function is one which calls itself.  Care
  19931.     must be taken when writing a recursive function because it is
  19932.     possible to make it recurse indefinitely.  You must make sure you
  19933.     have an adequate way of terminating the recursion.  The following
  19934.     simple function recursively counts to 10, using the static
  19935.     variable <VAR
  19936. CLASS="varname"
  19937. >$count</VAR
  19938. > to know when to stop:
  19939.    </P
  19940. ><P
  19941. >     <TABLE
  19942. WIDTH="100%"
  19943. BORDER="0"
  19944. CELLPADDING="0"
  19945. CELLSPACING="0"
  19946. CLASS="EXAMPLE"
  19947. ><TR
  19948. ><TD
  19949. ><DIV
  19950. CLASS="example"
  19951. ><A
  19952. NAME="AEN3588"
  19953. ></A
  19954. ><P
  19955. ><B
  19956. >Example 12-6. Static variables with recursive functions</B
  19957. ></P
  19958. ><TABLE
  19959. BORDER="0"
  19960. BGCOLOR="#E0E0E0"
  19961. CELLPADDING="5"
  19962. ><TR
  19963. ><TD
  19964. ><PRE
  19965. CLASS="php"
  19966. ><?php
  19967. function Test()
  19968. {
  19969.     static $count = 0;
  19970.  
  19971.     $count++;
  19972.     echo $count;
  19973.     if ($count < 10) {
  19974.         Test ();
  19975.     }
  19976.     $count--;
  19977. }
  19978. ?></PRE
  19979. ></TD
  19980. ></TR
  19981. ></TABLE
  19982. ></DIV
  19983. ></TD
  19984. ></TR
  19985. ></TABLE
  19986. >
  19987.    </P
  19988. ><DIV
  19989. CLASS="note"
  19990. ><BLOCKQUOTE
  19991. CLASS="note"
  19992. ><P
  19993. ><B
  19994. >Note: </B
  19995. >  
  19996.        Static variables maybe declared as seen in the examples above. 
  19997.        Trying to assign values to these variables which are the 
  19998.        result of expressions will cause a parse error.
  19999.      </P
  20000. ><P
  20001. >  
  20002.       <TABLE
  20003. WIDTH="100%"
  20004. BORDER="0"
  20005. CELLPADDING="0"
  20006. CELLSPACING="0"
  20007. CLASS="EXAMPLE"
  20008. ><TR
  20009. ><TD
  20010. ><DIV
  20011. CLASS="example"
  20012. ><A
  20013. NAME="AEN3594"
  20014. ></A
  20015. ><P
  20016. ><B
  20017. >Example 12-7. Declaring static variables</B
  20018. ></P
  20019. ><TABLE
  20020. BORDER="0"
  20021. BGCOLOR="#E0E0E0"
  20022. CELLPADDING="5"
  20023. ><TR
  20024. ><TD
  20025. ><PRE
  20026. CLASS="php"
  20027. ><?php
  20028. function foo(){
  20029.     static $int = 0;          // correct 
  20030.     static $int = 1+2;        // wrong  (as it is an expression)
  20031.     static $int = sqrt(121);  // wrong  (as it is an expression too)
  20032.  
  20033.     $int++;
  20034.     echo $int;
  20035. }
  20036. ?></PRE
  20037. ></TD
  20038. ></TR
  20039. ></TABLE
  20040. ></DIV
  20041. ></TD
  20042. ></TR
  20043. ></TABLE
  20044. >
  20045.     </P
  20046. ></BLOCKQUOTE
  20047. ></DIV
  20048. ></DIV
  20049. ><DIV
  20050. CLASS="sect2"
  20051. ><HR><H3
  20052. CLASS="sect2"
  20053. ><A
  20054. NAME="language.variables.scope.references"
  20055. >References with global and static variables</A
  20056. ></H3
  20057. ><P
  20058. >     The Zend Engine 1, driving PHP 4, implements the
  20059.     <A
  20060. HREF="#language.variables.scope.static"
  20061. >static</A
  20062. > and 
  20063.     <A
  20064. HREF="#language.variables.scope.global"
  20065. >global</A
  20066. > modifier 
  20067.     for variables in terms of <A
  20068. HREF="#language.references"
  20069. >     references</A
  20070. >. For example, a true global variable
  20071.     imported inside a function scope with the <VAR
  20072. CLASS="literal"
  20073. >global</VAR
  20074. >
  20075.     statement actually creates a reference to the global variable. This can
  20076.     lead to unexpected behaviour which the following example addresses:
  20077.    </P
  20078. ><DIV
  20079. CLASS="informalexample"
  20080. ><P
  20081. ></P
  20082. ><A
  20083. NAME="AEN3604"
  20084. ></A
  20085. ><TABLE
  20086. BORDER="0"
  20087. BGCOLOR="#E0E0E0"
  20088. CELLPADDING="5"
  20089. ><TR
  20090. ><TD
  20091. ><PRE
  20092. CLASS="php"
  20093. ><?php
  20094. function test_global_ref() {
  20095.     global $obj;
  20096.     $obj = &new stdclass;
  20097. }
  20098.  
  20099. function test_global_noref() {
  20100.     global $obj;
  20101.     $obj = new stdclass;
  20102. }
  20103.  
  20104. test_global_ref();
  20105. var_dump($obj);
  20106. test_global_noref();
  20107. var_dump($obj);
  20108. ?></PRE
  20109. ></TD
  20110. ></TR
  20111. ></TABLE
  20112. ><P
  20113. ></P
  20114. ></DIV
  20115. ><P
  20116. >     Executing this example will result in the following output:
  20117.    </P
  20118. ><TABLE
  20119. BORDER="0"
  20120. BGCOLOR="#E0E0E0"
  20121. CELLPADDING="5"
  20122. ><TR
  20123. ><TD
  20124. ><PRE
  20125. CLASS="screen"
  20126. >NULL
  20127. object(stdClass)(0) {
  20128. }</PRE
  20129. ></TD
  20130. ></TR
  20131. ></TABLE
  20132. ><P
  20133. >     A similar behaviour applies to the <VAR
  20134. CLASS="literal"
  20135. >static</VAR
  20136. > statement.
  20137.     References are not stored statically:
  20138.    </P
  20139. ><DIV
  20140. CLASS="informalexample"
  20141. ><P
  20142. ></P
  20143. ><A
  20144. NAME="AEN3610"
  20145. ></A
  20146. ><TABLE
  20147. BORDER="0"
  20148. BGCOLOR="#E0E0E0"
  20149. CELLPADDING="5"
  20150. ><TR
  20151. ><TD
  20152. ><PRE
  20153. CLASS="php"
  20154. ><?php
  20155. function &get_instance_ref() {
  20156.     static $obj;
  20157.  
  20158.     echo "Static object: ";
  20159.     var_dump($obj);
  20160.     if (!isset($obj)) {
  20161.         // Assign a reference to the static variable
  20162.         $obj = &new stdclass;
  20163.     }
  20164.     $obj->property++;
  20165.     return $obj;
  20166. }
  20167.  
  20168. function &get_instance_noref() {
  20169.     static $obj;
  20170.  
  20171.     echo "Static object: ";
  20172.     var_dump($obj);
  20173.     if (!isset($obj)) {
  20174.         // Assign the object to the static variable
  20175.         $obj = new stdclass;
  20176.     }
  20177.     $obj->property++;
  20178.     return $obj;
  20179. }
  20180.  
  20181. $obj1 = get_instance_ref();
  20182. $still_obj1 = get_instance_ref();
  20183. echo "\n";
  20184. $obj2 = get_instance_noref();
  20185. $still_obj2 = get_instance_noref();
  20186. ?></PRE
  20187. ></TD
  20188. ></TR
  20189. ></TABLE
  20190. ><P
  20191. ></P
  20192. ></DIV
  20193. ><P
  20194. >     Executing this example will result in the following output:
  20195.    </P
  20196. ><TABLE
  20197. BORDER="0"
  20198. BGCOLOR="#E0E0E0"
  20199. CELLPADDING="5"
  20200. ><TR
  20201. ><TD
  20202. ><PRE
  20203. CLASS="screen"
  20204. >Static object: NULL
  20205. Static object: NULL
  20206.  
  20207. Static object: NULL
  20208. Static object: object(stdClass)(1) {
  20209.   ["property"]=>
  20210.   int(1)
  20211. }</PRE
  20212. ></TD
  20213. ></TR
  20214. ></TABLE
  20215. ><P
  20216. >     This example demonstrates that when assigning a reference to a static
  20217.     variable, it's not <SPAN
  20218. CLASS="emphasis"
  20219. ><I
  20220. CLASS="emphasis"
  20221. >remembered</I
  20222. ></SPAN
  20223. > when you call the
  20224.     <VAR
  20225. CLASS="literal"
  20226. >&get_instance_ref()</VAR
  20227. > function a second time.
  20228.    </P
  20229. ></DIV
  20230. ></DIV
  20231. ><DIV
  20232. CLASS="sect1"
  20233. ><HR><H2
  20234. CLASS="sect1"
  20235. ><A
  20236. NAME="language.variables.variable"
  20237. >Variable variables</A
  20238. ></H2
  20239. ><P
  20240. >     Sometimes it is convenient to be able to have variable variable
  20241.     names.  That is, a variable name which can be set and used
  20242.     dynamically.  A normal variable is set with a statement such as:
  20243.    </P
  20244. ><DIV
  20245. CLASS="informalexample"
  20246. ><P
  20247. ></P
  20248. ><A
  20249. NAME="AEN3620"
  20250. ></A
  20251. ><TABLE
  20252. BORDER="0"
  20253. BGCOLOR="#E0E0E0"
  20254. CELLPADDING="5"
  20255. ><TR
  20256. ><TD
  20257. ><PRE
  20258. CLASS="php"
  20259. ><?php
  20260. $a = "hello";
  20261. ?></PRE
  20262. ></TD
  20263. ></TR
  20264. ></TABLE
  20265. ><P
  20266. ></P
  20267. ></DIV
  20268. ><P
  20269. >     A variable variable takes the value of a variable and treats that
  20270.     as the name of a variable.  In the above example,
  20271.     <SPAN
  20272. CLASS="emphasis"
  20273. ><I
  20274. CLASS="emphasis"
  20275. >hello</I
  20276. ></SPAN
  20277. >, can be used as the name of a variable
  20278.     by using two dollar signs. i.e.
  20279.    </P
  20280. ><DIV
  20281. CLASS="informalexample"
  20282. ><P
  20283. ></P
  20284. ><A
  20285. NAME="AEN3624"
  20286. ></A
  20287. ><TABLE
  20288. BORDER="0"
  20289. BGCOLOR="#E0E0E0"
  20290. CELLPADDING="5"
  20291. ><TR
  20292. ><TD
  20293. ><PRE
  20294. CLASS="php"
  20295. ><?php
  20296. $$a = "world";
  20297. ?></PRE
  20298. ></TD
  20299. ></TR
  20300. ></TABLE
  20301. ><P
  20302. ></P
  20303. ></DIV
  20304. ><P
  20305. >     At this point two variables have been defined and stored in the
  20306.     PHP symbol tree: <VAR
  20307. CLASS="varname"
  20308. >$a</VAR
  20309. > with contents "hello" and
  20310.     <VAR
  20311. CLASS="varname"
  20312. >$hello</VAR
  20313. > with contents "world".  Therefore, this
  20314.     statement:
  20315.    </P
  20316. ><DIV
  20317. CLASS="informalexample"
  20318. ><P
  20319. ></P
  20320. ><A
  20321. NAME="AEN3629"
  20322. ></A
  20323. ><TABLE
  20324. BORDER="0"
  20325. BGCOLOR="#E0E0E0"
  20326. CELLPADDING="5"
  20327. ><TR
  20328. ><TD
  20329. ><PRE
  20330. CLASS="php"
  20331. ><?php
  20332. echo "$a ${$a}";
  20333. ?></PRE
  20334. ></TD
  20335. ></TR
  20336. ></TABLE
  20337. ><P
  20338. ></P
  20339. ></DIV
  20340. ><P
  20341. >     produces the exact same output as:
  20342.    </P
  20343. ><DIV
  20344. CLASS="informalexample"
  20345. ><P
  20346. ></P
  20347. ><A
  20348. NAME="AEN3632"
  20349. ></A
  20350. ><TABLE
  20351. BORDER="0"
  20352. BGCOLOR="#E0E0E0"
  20353. CELLPADDING="5"
  20354. ><TR
  20355. ><TD
  20356. ><PRE
  20357. CLASS="php"
  20358. ><?php
  20359. echo "$a $hello";
  20360. ?></PRE
  20361. ></TD
  20362. ></TR
  20363. ></TABLE
  20364. ><P
  20365. ></P
  20366. ></DIV
  20367. ><P
  20368. >     i.e. they both produce: <SAMP
  20369. CLASS="computeroutput"
  20370. >hello world</SAMP
  20371. >.
  20372.    </P
  20373. ><P
  20374. >     In order to use variable variables with arrays, you have to
  20375.     resolve an ambiguity problem.  That is, if you write
  20376.     <VAR
  20377. CLASS="varname"
  20378. >$$a[1]</VAR
  20379. > then the parser needs to know if you
  20380.     meant to use <VAR
  20381. CLASS="varname"
  20382. >$a[1]</VAR
  20383. > as a variable, or if you
  20384.     wanted <VAR
  20385. CLASS="varname"
  20386. >$$a</VAR
  20387. > as the variable and then the [1]
  20388.     index from that variable.  The syntax for resolving this ambiguity
  20389.     is: <VAR
  20390. CLASS="varname"
  20391. >${$a[1]}</VAR
  20392. > for the first case and
  20393.     <VAR
  20394. CLASS="varname"
  20395. >${$a}[1]</VAR
  20396. > for the second.
  20397.    </P
  20398. ><DIV
  20399. CLASS="warning"
  20400. ><P
  20401. ></P
  20402. ><TABLE
  20403. CLASS="warning"
  20404. BORDER="1"
  20405. WIDTH="100%"
  20406. ><TR
  20407. ><TD
  20408. ALIGN="CENTER"
  20409. ><B
  20410. >Warning</B
  20411. ></TD
  20412. ></TR
  20413. ><TR
  20414. ><TD
  20415. ALIGN="LEFT"
  20416. ><P
  20417. >      Please note that variable variables cannot be used with PHP's 
  20418.      <A
  20419. HREF="#language.variables.superglobals"
  20420. >Superglobal arrays</A
  20421. >
  20422.      within functions or class methods.
  20423.     </P
  20424. ></TD
  20425. ></TR
  20426. ></TABLE
  20427. ></DIV
  20428. ></DIV
  20429. ><DIV
  20430. CLASS="sect1"
  20431. ><HR><H2
  20432. CLASS="sect1"
  20433. ><A
  20434. NAME="language.variables.external"
  20435. >Variables from outside PHP</A
  20436. ></H2
  20437. ><DIV
  20438. CLASS="sect2"
  20439. ><H3
  20440. CLASS="sect2"
  20441. ><A
  20442. NAME="language.variables.external.form"
  20443. >HTML Forms (GET and POST)</A
  20444. ></H3
  20445. ><P
  20446. >      When a form is submitted to a PHP script, the information from 
  20447.      that form is automatically made available to the script.  There 
  20448.      are many ways to access this information, for example:
  20449.     </P
  20450. ><P
  20451. >      <TABLE
  20452. WIDTH="100%"
  20453. BORDER="0"
  20454. CELLPADDING="0"
  20455. CELLSPACING="0"
  20456. CLASS="EXAMPLE"
  20457. ><TR
  20458. ><TD
  20459. ><DIV
  20460. CLASS="example"
  20461. ><A
  20462. NAME="AEN3651"
  20463. ></A
  20464. ><P
  20465. ><B
  20466. >Example 12-8. A simple HTML form</B
  20467. ></P
  20468. ><TABLE
  20469. BORDER="0"
  20470. BGCOLOR="#E0E0E0"
  20471. CELLPADDING="5"
  20472. ><TR
  20473. ><TD
  20474. ><PRE
  20475. CLASS="html"
  20476. ><form action="foo.php" method="post">
  20477.     Name:  <input type="text" name="username" /><br />
  20478.     Email: <input type="text" name="email" /><br />
  20479.     <input type="submit" name="submit" value="Submit me!" />
  20480. </form></PRE
  20481. ></TD
  20482. ></TR
  20483. ></TABLE
  20484. ></DIV
  20485. ></TD
  20486. ></TR
  20487. ></TABLE
  20488. >
  20489.     </P
  20490. ><P
  20491. >      Depending on your particular setup and personal preferences, there 
  20492.      are many ways to access data from your HTML forms.  Some examples are:
  20493.     </P
  20494. ><P
  20495. >      <TABLE
  20496. WIDTH="100%"
  20497. BORDER="0"
  20498. CELLPADDING="0"
  20499. CELLSPACING="0"
  20500. CLASS="EXAMPLE"
  20501. ><TR
  20502. ><TD
  20503. ><DIV
  20504. CLASS="example"
  20505. ><A
  20506. NAME="AEN3656"
  20507. ></A
  20508. ><P
  20509. ><B
  20510. >Example 12-9. Accessing data from a simple POST HTML form</B
  20511. ></P
  20512. ><TABLE
  20513. BORDER="0"
  20514. BGCOLOR="#E0E0E0"
  20515. CELLPADDING="5"
  20516. ><TR
  20517. ><TD
  20518. ><PRE
  20519. CLASS="html"
  20520. ><?php 
  20521. // Available since PHP 4.1.0
  20522.  
  20523.    echo $_POST['username'];
  20524.    echo $_REQUEST['username'];
  20525.  
  20526.    import_request_variables('p', 'p_');
  20527.    echo $p_username;
  20528.  
  20529. // Available since PHP 3. As of PHP 5.0.0, these long predefined
  20530. // variables can be disabled with the register_long_arrays directive.
  20531.  
  20532.    echo $HTTP_POST_VARS['username'];
  20533.  
  20534. // Available if the PHP directive register_globals = on. As of 
  20535. // PHP 4.2.0 the default value of register_globals = off.
  20536. // Using/relying on this method is not preferred.
  20537.  
  20538.    echo $username;
  20539. ?></PRE
  20540. ></TD
  20541. ></TR
  20542. ></TABLE
  20543. ></DIV
  20544. ></TD
  20545. ></TR
  20546. ></TABLE
  20547. >
  20548.     </P
  20549. ><P
  20550. >      Using a GET form is similar except you'll use the appropriate
  20551.      GET predefined variable instead.  GET also applies to the
  20552.      QUERY_STRING (the information after the '?' in a URL).  So,
  20553.      for example, <VAR
  20554. CLASS="literal"
  20555. >http://www.example.com/test.php?id=3</VAR
  20556. >
  20557.      contains GET data which is accessible with <VAR
  20558. CLASS="varname"
  20559. >$_GET['id']</VAR
  20560. >.
  20561.      See also <A
  20562. HREF="#reserved.variables.request"
  20563. >$_REQUEST</A
  20564. > and 
  20565.      <A
  20566. HREF="#function.import-request-variables"
  20567. ><B
  20568. CLASS="function"
  20569. >import_request_variables()</B
  20570. ></A
  20571. >.
  20572.     </P
  20573. ><DIV
  20574. CLASS="note"
  20575. ><BLOCKQUOTE
  20576. CLASS="note"
  20577. ><P
  20578. ><B
  20579. >Note: </B
  20580. >
  20581.       <A
  20582. HREF="#language.variables.superglobals"
  20583. >Superglobal arrays</A
  20584. >, 
  20585.       like <VAR
  20586. CLASS="varname"
  20587. >$_POST</VAR
  20588. > and <VAR
  20589. CLASS="varname"
  20590. >$_GET</VAR
  20591. >, became 
  20592.       available in PHP 4.1.0
  20593.      </P
  20594. ></BLOCKQUOTE
  20595. ></DIV
  20596. ><P
  20597. >      As shown, before PHP 4.2.0 the default value for <A
  20598. HREF="#ini.register-globals"
  20599. >register_globals</A
  20600. >
  20601.      was <SPAN
  20602. CLASS="emphasis"
  20603. ><I
  20604. CLASS="emphasis"
  20605. >on</I
  20606. ></SPAN
  20607. >.  And, in PHP 3 it was always on.  The PHP 
  20608.      community is encouraging all to not rely on this directive 
  20609.      as it's preferred to assume it's <SPAN
  20610. CLASS="emphasis"
  20611. ><I
  20612. CLASS="emphasis"
  20613. >off</I
  20614. ></SPAN
  20615. > and code 
  20616.      accordingly.
  20617.     </P
  20618. ><DIV
  20619. CLASS="note"
  20620. ><BLOCKQUOTE
  20621. CLASS="note"
  20622. ><P
  20623. ><B
  20624. >Note: </B
  20625. >
  20626.       The <A
  20627. HREF="#ini.magic-quotes-gpc"
  20628. >magic_quotes_gpc</A
  20629. > 
  20630.       configuration directive affects Get, Post and Cookie values.  If 
  20631.       turned on, value (It's "PHP!") will automagically become (It\'s \"PHP!\").
  20632.       Escaping is needed for DB insertion.  See also 
  20633.       <A
  20634. HREF="#function.addslashes"
  20635. ><B
  20636. CLASS="function"
  20637. >addslashes()</B
  20638. ></A
  20639. >, <A
  20640. HREF="#function.stripslashes"
  20641. ><B
  20642. CLASS="function"
  20643. >stripslashes()</B
  20644. ></A
  20645. > and 
  20646.       <A
  20647. HREF="#ini.magic-quotes-sybase"
  20648. >magic_quotes_sybase</A
  20649. >.
  20650.      </P
  20651. ></BLOCKQUOTE
  20652. ></DIV
  20653. ><P
  20654. >      PHP also understands arrays in the context of form variables 
  20655.      (see the <A
  20656. HREF="#faq.html"
  20657. >related faq</A
  20658. >).  You may, 
  20659.      for example, group related variables together, or use this 
  20660.      feature to retrieve values from a multiple select input.  For 
  20661.      example, let's post a form to itself and upon submission display 
  20662.      the data:
  20663.     </P
  20664. ><P
  20665. >      <TABLE
  20666. WIDTH="100%"
  20667. BORDER="0"
  20668. CELLPADDING="0"
  20669. CELLSPACING="0"
  20670. CLASS="EXAMPLE"
  20671. ><TR
  20672. ><TD
  20673. ><DIV
  20674. CLASS="example"
  20675. ><A
  20676. NAME="AEN3682"
  20677. ></A
  20678. ><P
  20679. ><B
  20680. >Example 12-10. More complex form variables</B
  20681. ></P
  20682. ><TABLE
  20683. BORDER="0"
  20684. BGCOLOR="#E0E0E0"
  20685. CELLPADDING="5"
  20686. ><TR
  20687. ><TD
  20688. ><PRE
  20689. CLASS="php"
  20690. ><?php
  20691. if (isset($_POST['action']) && $_POST['action'] == 'submitted') {
  20692.     echo '<pre>';
  20693.     print_r($_POST);
  20694.     echo '<a href="'. $_SERVER['PHP_SELF'] .'">Please try again</a>';
  20695.  
  20696.     echo '</pre>';
  20697. } else {
  20698. ?>
  20699. <form action="<?php echo $_SERVER['PHP_SELF']; ?>" method="post">
  20700.     Name:  <input type="text" name="personal[name]" /><br />
  20701.     Email: <input type="text" name="personal[email]" /><br />
  20702.     Beer: <br />
  20703.     <select multiple name="beer[]">
  20704.         <option value="warthog">Warthog</option>
  20705.         <option value="guinness">Guinness</option>
  20706.         <option value="stuttgarter">Stuttgarter Schwabenbr├ñu</option>
  20707.     </select><br />
  20708.     <input type="hidden" name="action" value="submitted" />
  20709.     <input type="submit" name="submit" value="submit me!" />
  20710. </form>
  20711. <?php
  20712. }
  20713. ?></PRE
  20714. ></TD
  20715. ></TR
  20716. ></TABLE
  20717. ></DIV
  20718. ></TD
  20719. ></TR
  20720. ></TABLE
  20721. >
  20722.     </P
  20723. ><P
  20724. >      In PHP 3, the array form variable usage is limited to
  20725.      single-dimensional arrays. As of PHP 4, no such restriction applies.
  20726.     </P
  20727. ><DIV
  20728. CLASS="sect3"
  20729. ><HR><H4
  20730. CLASS="sect3"
  20731. ><A
  20732. NAME="language.variables.external.form.submit"
  20733. >IMAGE SUBMIT variable names</A
  20734. ></H4
  20735. ><P
  20736. >       When submitting a form, it is possible to use an image instead
  20737.       of the standard submit button with a tag like:
  20738.      </P
  20739. ><DIV
  20740. CLASS="informalexample"
  20741. ><P
  20742. ></P
  20743. ><A
  20744. NAME="AEN3689"
  20745. ></A
  20746. ><TABLE
  20747. BORDER="0"
  20748. BGCOLOR="#E0E0E0"
  20749. CELLPADDING="5"
  20750. ><TR
  20751. ><TD
  20752. ><PRE
  20753. CLASS="html"
  20754. ><input type="image" src="image.gif" name="sub" /></PRE
  20755. ></TD
  20756. ></TR
  20757. ></TABLE
  20758. ><P
  20759. ></P
  20760. ></DIV
  20761. ><P
  20762. >       When the user clicks somewhere on the image, the accompanying
  20763.       form will be transmitted to the server with two additional
  20764.       variables, sub_x and sub_y. These contain the coordinates of the
  20765.       user click within the image.  The experienced may note that the
  20766.       actual variable names sent by the browser contains a period
  20767.       rather than an underscore, but PHP converts the period to an
  20768.       underscore automatically.
  20769.      </P
  20770. ></DIV
  20771. ></DIV
  20772. ><DIV
  20773. CLASS="sect2"
  20774. ><HR><H3
  20775. CLASS="sect2"
  20776. ><A
  20777. NAME="language.variables.external.cookies"
  20778. >HTTP Cookies</A
  20779. ></H3
  20780. ><P
  20781. >      PHP transparently supports HTTP cookies as defined by <A
  20782. HREF="http://www.netscape.com/newsref/std/cookie_spec.html"
  20783. TARGET="_top"
  20784. >Netscape's Spec</A
  20785. >.  Cookies are a
  20786.      mechanism for storing data in the remote browser and thus
  20787.      tracking or identifying return users.  You can set cookies using
  20788.      the <A
  20789. HREF="#function.setcookie"
  20790. ><B
  20791. CLASS="function"
  20792. >setcookie()</B
  20793. ></A
  20794. > function.  Cookies are part of
  20795.      the HTTP header, so the SetCookie function must be called before
  20796.      any output is sent to the browser.  This is the same restriction
  20797.      as for the <A
  20798. HREF="#function.header"
  20799. ><B
  20800. CLASS="function"
  20801. >header()</B
  20802. ></A
  20803. > function.  Cookie data 
  20804.      is then available in the appropriate cookie data arrays, such 
  20805.      as <VAR
  20806. CLASS="varname"
  20807. >$_COOKIE</VAR
  20808. >, <VAR
  20809. CLASS="varname"
  20810. >$HTTP_COOKIE_VARS</VAR
  20811. > 
  20812.      as well as in <VAR
  20813. CLASS="varname"
  20814. >$_REQUEST</VAR
  20815. >.  See the 
  20816.      <A
  20817. HREF="#function.setcookie"
  20818. ><B
  20819. CLASS="function"
  20820. >setcookie()</B
  20821. ></A
  20822. > manual page for more details and 
  20823.      examples.
  20824.     </P
  20825. ><P
  20826. >      If you wish to assign multiple values to a single cookie variable, you 
  20827.      may assign it as an array.  For example:
  20828.     </P
  20829. ><DIV
  20830. CLASS="informalexample"
  20831. ><P
  20832. ></P
  20833. ><A
  20834. NAME="AEN3703"
  20835. ></A
  20836. ><TABLE
  20837. BORDER="0"
  20838. BGCOLOR="#E0E0E0"
  20839. CELLPADDING="5"
  20840. ><TR
  20841. ><TD
  20842. ><PRE
  20843. CLASS="php"
  20844. ><?php
  20845.   setcookie("MyCookie[foo]", "Testing 1", time()+3600);
  20846.   setcookie("MyCookie[bar]", "Testing 2", time()+3600);
  20847. ?></PRE
  20848. ></TD
  20849. ></TR
  20850. ></TABLE
  20851. ><P
  20852. ></P
  20853. ></DIV
  20854. ><P
  20855. >      That will create two separate cookies although MyCookie will now 
  20856.      be a single array in your script.  If you want to set just one cookie 
  20857.      with multiple values, consider using <A
  20858. HREF="#function.serialize"
  20859. ><B
  20860. CLASS="function"
  20861. >serialize()</B
  20862. ></A
  20863. > or 
  20864.      <A
  20865. HREF="#function.explode"
  20866. ><B
  20867. CLASS="function"
  20868. >explode()</B
  20869. ></A
  20870. > on the value first.
  20871.     </P
  20872. ><P
  20873. >      Note that a cookie will replace a previous cookie by the same
  20874.      name in your browser unless the path or domain is different.  So,
  20875.      for a shopping cart application you may want to keep a counter
  20876.      and pass this along.  i.e.
  20877.     </P
  20878. ><TABLE
  20879. WIDTH="100%"
  20880. BORDER="0"
  20881. CELLPADDING="0"
  20882. CELLSPACING="0"
  20883. CLASS="EXAMPLE"
  20884. ><TR
  20885. ><TD
  20886. ><DIV
  20887. CLASS="example"
  20888. ><A
  20889. NAME="AEN3709"
  20890. ></A
  20891. ><P
  20892. ><B
  20893. >Example 12-11. A <A
  20894. HREF="#function.setcookie"
  20895. ><B
  20896. CLASS="function"
  20897. >setcookie()</B
  20898. ></A
  20899. > example</B
  20900. ></P
  20901. ><TABLE
  20902. BORDER="0"
  20903. BGCOLOR="#E0E0E0"
  20904. CELLPADDING="5"
  20905. ><TR
  20906. ><TD
  20907. ><PRE
  20908. CLASS="php"
  20909. ><?php
  20910. if (isset($_COOKIE['count'])) {
  20911.     $count = $_COOKIE['count'] + 1;
  20912. } else {
  20913.     $count = 1;
  20914. }
  20915. setcookie("count", $count, time()+3600);
  20916. setcookie("Cart[$count]", $item, time()+3600);
  20917. ?></PRE
  20918. ></TD
  20919. ></TR
  20920. ></TABLE
  20921. ></DIV
  20922. ></TD
  20923. ></TR
  20924. ></TABLE
  20925. ></DIV
  20926. ><DIV
  20927. CLASS="sect2"
  20928. ><HR><H3
  20929. CLASS="sect2"
  20930. ><A
  20931. NAME="language.variables.external.dot-in-names"
  20932. >Dots in incoming variable names</A
  20933. ></H3
  20934. ><P
  20935. >      Typically, PHP does not alter the names of variables when they
  20936.      are passed into a script. However, it should be noted that the
  20937.      dot (period, full stop) is not a valid character in a PHP
  20938.      variable name. For the reason, look at it:
  20939.      <TABLE
  20940. BORDER="0"
  20941. BGCOLOR="#E0E0E0"
  20942. CELLPADDING="5"
  20943. ><TR
  20944. ><TD
  20945. ><PRE
  20946. CLASS="php"
  20947. ><?php
  20948. $varname.ext;  /* invalid variable name */
  20949. ?></PRE
  20950. ></TD
  20951. ></TR
  20952. ></TABLE
  20953. >
  20954.      Now, what the parser sees is a variable named
  20955.      <VAR
  20956. CLASS="varname"
  20957. >$varname</VAR
  20958. >, followed by the string concatenation
  20959.      operator, followed by the barestring (i.e. unquoted string which
  20960.      doesn't match any known key or reserved words) 'ext'. Obviously,
  20961.      this doesn't have the intended result.
  20962.     </P
  20963. ><P
  20964. >      For this reason, it is important to note that PHP will
  20965.      automatically replace any dots in incoming variable names with
  20966.      underscores.
  20967.     </P
  20968. ></DIV
  20969. ><DIV
  20970. CLASS="sect2"
  20971. ><HR><H3
  20972. CLASS="sect2"
  20973. ><A
  20974. NAME="language.variables.determining-type-of"
  20975. >Determining variable types</A
  20976. ></H3
  20977. ><P
  20978. >      Because PHP determines the types of variables and converts them
  20979.      (generally) as needed, it is not always obvious what type a given
  20980.      variable is at any one time.  PHP includes several functions
  20981.      which find out what type a variable is, such as:
  20982.      <A
  20983. HREF="#function.gettype"
  20984. ><B
  20985. CLASS="function"
  20986. >gettype()</B
  20987. ></A
  20988. >, <A
  20989. HREF="#function.is-array"
  20990. ><B
  20991. CLASS="function"
  20992. >is_array()</B
  20993. ></A
  20994. >,
  20995.      <A
  20996. HREF="#function.is-float"
  20997. ><B
  20998. CLASS="function"
  20999. >is_float()</B
  21000. ></A
  21001. >, <A
  21002. HREF="#function.is-int"
  21003. ><B
  21004. CLASS="function"
  21005. >is_int()</B
  21006. ></A
  21007. >,
  21008.      <A
  21009. HREF="#function.is-object"
  21010. ><B
  21011. CLASS="function"
  21012. >is_object()</B
  21013. ></A
  21014. >, and
  21015.      <A
  21016. HREF="#function.is-string"
  21017. ><B
  21018. CLASS="function"
  21019. >is_string()</B
  21020. ></A
  21021. >.  See also the chapter on 
  21022.      <A
  21023. HREF="#language.types"
  21024. >Types</A
  21025. >.
  21026.     </P
  21027. ></DIV
  21028. ></DIV
  21029. ></DIV
  21030. ><DIV
  21031. CLASS="chapter"
  21032. ><HR><H1
  21033. ><A
  21034. NAME="language.constants"
  21035. >Chapter 13. Constants</A
  21036. ></H1
  21037. ><P
  21038. >    A constant is an identifier (name) for a simple value. As the name
  21039.    suggests, that value cannot change during the execution of the
  21040.    script (except for <A
  21041. HREF="#language.constants.predefined"
  21042. >    magic constants</A
  21043. >, which aren't actually constants).
  21044.    A constant is case-sensitive by default. By convention, constant 
  21045.    identifiers are always uppercase.
  21046.   </P
  21047. ><P
  21048. >    The name of a constant follows the same rules as any label in PHP. A 
  21049.    valid constant name starts with a letter or underscore, followed
  21050.    by any number of letters, numbers, or underscores. As a regular
  21051.    expression, it would be expressed thusly:
  21052.    <VAR
  21053. CLASS="literal"
  21054. >[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*</VAR
  21055. >
  21056.   </P
  21057. ><P
  21058. >    <TABLE
  21059. WIDTH="100%"
  21060. BORDER="0"
  21061. CELLPADDING="0"
  21062. CELLSPACING="0"
  21063. CLASS="EXAMPLE"
  21064. ><TR
  21065. ><TD
  21066. ><DIV
  21067. CLASS="example"
  21068. ><A
  21069. NAME="AEN3736"
  21070. ></A
  21071. ><P
  21072. ><B
  21073. >Example 13-1. Valid and invalid constant names</B
  21074. ></P
  21075. ><TABLE
  21076. BORDER="0"
  21077. BGCOLOR="#E0E0E0"
  21078. CELLPADDING="5"
  21079. ><TR
  21080. ><TD
  21081. ><PRE
  21082. CLASS="php"
  21083. ><?php
  21084.  
  21085. // Valid constant names
  21086. define("FOO",     "something");
  21087. define("FOO2",    "something else");
  21088. define("FOO_BAR", "something more")
  21089.  
  21090. // Invalid constant names
  21091. define("2FOO",    "something");
  21092.  
  21093. // This is valid, but should be avoided:
  21094. // PHP may one day provide a magical constant
  21095. // that will break your script
  21096. define("__FOO__", "something"); 
  21097.  
  21098. ?></PRE
  21099. ></TD
  21100. ></TR
  21101. ></TABLE
  21102. ></DIV
  21103. ></TD
  21104. ></TR
  21105. ></TABLE
  21106. >
  21107.   </P
  21108. ><DIV
  21109. CLASS="note"
  21110. ><BLOCKQUOTE
  21111. CLASS="note"
  21112. ><P
  21113. ><B
  21114. >Note: </B
  21115. >
  21116.     For our purposes here, a letter is a-z, A-Z, and the ASCII
  21117.     characters from 127 through 255 (0x7f-0xff).
  21118.    </P
  21119. ></BLOCKQUOTE
  21120. ></DIV
  21121. ><P
  21122. >    Like <A
  21123. HREF="#language.variables.predefined"
  21124. >superglobals</A
  21125. >, the scope of a constant is global.  You 
  21126.    can access constants anywhere in your script without regard to scope.  
  21127.    For more information on scope, read the manual section on
  21128.    <A
  21129. HREF="#language.variables.scope"
  21130. >variable scope</A
  21131. >.
  21132.   </P
  21133. ><DIV
  21134. CLASS="sect1"
  21135. ><HR><H2
  21136. CLASS="sect1"
  21137. ><A
  21138. NAME="language.constants.syntax"
  21139. >Syntax</A
  21140. ></H2
  21141. ><P
  21142. >     You can define a constant by using the 
  21143.     <A
  21144. HREF="#function.define"
  21145. ><B
  21146. CLASS="function"
  21147. >define()</B
  21148. ></A
  21149. >-function. Once a constant is defined,
  21150.     it can never be changed or undefined.
  21151.    </P
  21152. ><P
  21153. >     Only scalar data (<A
  21154. HREF="#language.types.boolean"
  21155. ><B
  21156. CLASS="type"
  21157. >boolean</B
  21158. ></A
  21159. >, <A
  21160. HREF="#language.types.integer"
  21161. ><B
  21162. CLASS="type"
  21163. >integer</B
  21164. ></A
  21165. >, 
  21166.     <A
  21167. HREF="#language.types.float"
  21168. ><B
  21169. CLASS="type"
  21170. >float</B
  21171. ></A
  21172. > and <A
  21173. HREF="#language.types.string"
  21174. ><B
  21175. CLASS="type"
  21176. >string</B
  21177. ></A
  21178. >) can be contained 
  21179.     in constants.
  21180.    </P
  21181. ><P
  21182. >     You can get the value of a constant by simply specifying its name.
  21183.     Unlike with variables, you should <SPAN
  21184. CLASS="emphasis"
  21185. ><I
  21186. CLASS="emphasis"
  21187. >not</I
  21188. ></SPAN
  21189. > prepend
  21190.     a constant with a <VAR
  21191. CLASS="literal"
  21192. >$</VAR
  21193. >.
  21194.     You can also use the function <A
  21195. HREF="#function.constant"
  21196. ><B
  21197. CLASS="function"
  21198. >constant()</B
  21199. ></A
  21200. > to
  21201.     read a constant's value if you wish to obtain the constant's name
  21202.     dynamically. 
  21203.     Use <A
  21204. HREF="#function.get-defined-constants"
  21205. ><B
  21206. CLASS="function"
  21207. >get_defined_constants()</B
  21208. ></A
  21209. > to get a list of 
  21210.     all defined constants.
  21211.    </P
  21212. ><DIV
  21213. CLASS="note"
  21214. ><BLOCKQUOTE
  21215. CLASS="note"
  21216. ><P
  21217. ><B
  21218. >Note: </B
  21219. >
  21220.      Constants and (global) variables are in a different namespace. 
  21221.      This implies that for example <TT
  21222. CLASS="constant"
  21223. ><B
  21224. >TRUE</B
  21225. ></TT
  21226. > and 
  21227.      <VAR
  21228. CLASS="varname"
  21229. >$TRUE</VAR
  21230. > are generally different.
  21231.     </P
  21232. ></BLOCKQUOTE
  21233. ></DIV
  21234. ><P
  21235. >     If you use an undefined constant, PHP assumes that you mean
  21236.     the name of the constant itself, just as if you called it as
  21237.     a <A
  21238. HREF="#language.types.string"
  21239. ><B
  21240. CLASS="type"
  21241. >string</B
  21242. ></A
  21243. > (CONSTANT vs "CONSTANT").  An error of level
  21244.     <A
  21245. HREF="#ref.errorfunc"
  21246. >E_NOTICE</A
  21247. > will be issued
  21248.     when this happens.  See also the manual entry on why 
  21249.     <A
  21250. HREF="#language.types.array.foo-bar"
  21251. >$foo[bar]</A
  21252. > is
  21253.     wrong (unless you first <A
  21254. HREF="#function.define"
  21255. ><B
  21256. CLASS="function"
  21257. >define()</B
  21258. ></A
  21259. >
  21260.     <VAR
  21261. CLASS="literal"
  21262. >bar</VAR
  21263. > as a constant).  If you simply want to check if a
  21264.     constant is set, use the <A
  21265. HREF="#function.defined"
  21266. ><B
  21267. CLASS="function"
  21268. >defined()</B
  21269. ></A
  21270. > function.
  21271.    </P
  21272. ><P
  21273. >     These are the differences between constants and variables:
  21274.     <P
  21275. ></P
  21276. ><UL
  21277. ><LI
  21278. ><P
  21279. >        Constants do not have a dollar sign (<VAR
  21280. CLASS="literal"
  21281. >$</VAR
  21282. >)
  21283.        before them;
  21284.       </P
  21285. ></LI
  21286. ><LI
  21287. ><P
  21288. >        Constants may only be defined using the
  21289.        <A
  21290. HREF="#function.define"
  21291. ><B
  21292. CLASS="function"
  21293. >define()</B
  21294. ></A
  21295. > function, not by simple assignment;
  21296.       </P
  21297. ></LI
  21298. ><LI
  21299. ><P
  21300. >        Constants may be defined and accessed anywhere without regard
  21301.        to variable scoping rules;
  21302.       </P
  21303. ></LI
  21304. ><LI
  21305. ><P
  21306. >        Constants may not be redefined or undefined once they have been
  21307.        set; and
  21308.       </P
  21309. ></LI
  21310. ><LI
  21311. ><P
  21312. >        Constants may only evaluate to scalar values.
  21313.        </P
  21314. ></LI
  21315. ></UL
  21316. >
  21317.    </P
  21318. ><P
  21319. >     <TABLE
  21320. WIDTH="100%"
  21321. BORDER="0"
  21322. CELLPADDING="0"
  21323. CELLSPACING="0"
  21324. CLASS="EXAMPLE"
  21325. ><TR
  21326. ><TD
  21327. ><DIV
  21328. CLASS="example"
  21329. ><A
  21330. NAME="AEN3784"
  21331. ></A
  21332. ><P
  21333. ><B
  21334. >Example 13-2. Defining Constants</B
  21335. ></P
  21336. ><TABLE
  21337. BORDER="0"
  21338. BGCOLOR="#E0E0E0"
  21339. CELLPADDING="5"
  21340. ><TR
  21341. ><TD
  21342. ><PRE
  21343. CLASS="php"
  21344. ><?php
  21345. define("CONSTANT", "Hello world.");
  21346. echo CONSTANT; // outputs "Hello world."
  21347. echo Constant; // outputs "Constant" and issues a notice.
  21348. ?></PRE
  21349. ></TD
  21350. ></TR
  21351. ></TABLE
  21352. ></DIV
  21353. ></TD
  21354. ></TR
  21355. ></TABLE
  21356. >
  21357.  
  21358.    </P
  21359. ></DIV
  21360. ><DIV
  21361. CLASS="sect1"
  21362. ><HR><H2
  21363. CLASS="sect1"
  21364. ><A
  21365. NAME="language.constants.predefined"
  21366. >Magic constants</A
  21367. ></H2
  21368. ><P
  21369. >     PHP provides a large number of <A
  21370. HREF="#reserved.constants"
  21371. >predefined constants</A
  21372. > to any script
  21373.     which it runs. Many of these constants, however, are created by
  21374.     various extensions, and will only be present when those extensions
  21375.     are available, either via dynamic loading or because they have
  21376.     been compiled in.
  21377.    </P
  21378. ><P
  21379. >     There are five magical constants that change depending on
  21380.     where they are used.  For example, the value of
  21381.     <TT
  21382. CLASS="constant"
  21383. ><B
  21384. >__LINE__</B
  21385. ></TT
  21386. > depends on the line that it's
  21387.     used on in your script. These special constants are 
  21388.     case-insensitive and are as follows:
  21389.    </P
  21390. ><P
  21391. >     <DIV
  21392. CLASS="table"
  21393. ><A
  21394. NAME="AEN3794"
  21395. ></A
  21396. ><P
  21397. ><B
  21398. >Table 13-1. A few "magical" PHP constants</B
  21399. ></P
  21400. ><TABLE
  21401. BORDER="1"
  21402. CLASS="CALSTABLE"
  21403. ><COL><COL><THEAD
  21404. ><TR
  21405. ><TH
  21406. >Name</TH
  21407. ><TH
  21408. >Description</TH
  21409. ></TR
  21410. ></THEAD
  21411. ><TBODY
  21412. ><TR
  21413. ><TD
  21414. ><TT
  21415. CLASS="constant"
  21416. ><B
  21417. >__LINE__</B
  21418. ></TT
  21419. ></TD
  21420. ><TD
  21421. >          The current line number of the file.
  21422.         </TD
  21423. ></TR
  21424. ><TR
  21425. ><TD
  21426. ><TT
  21427. CLASS="constant"
  21428. ><B
  21429. >__FILE__</B
  21430. ></TT
  21431. ></TD
  21432. ><TD
  21433. >          The full path and filename of the file.  If used inside an include,
  21434.          the name of the included file is returned.
  21435.         </TD
  21436. ></TR
  21437. ><TR
  21438. ><TD
  21439. ><TT
  21440. CLASS="constant"
  21441. ><B
  21442. >__FUNCTION__</B
  21443. ></TT
  21444. ></TD
  21445. ><TD
  21446. >          The function name. (Added in PHP 4.3.0)  As of PHP 5 this constant 
  21447.          returns the function name as it was declared (case-sensitive).  In
  21448.          PHP 4 its value is always lowercased.
  21449.         </TD
  21450. ></TR
  21451. ><TR
  21452. ><TD
  21453. ><TT
  21454. CLASS="constant"
  21455. ><B
  21456. >__CLASS__</B
  21457. ></TT
  21458. ></TD
  21459. ><TD
  21460. >          The class name. (Added in PHP 4.3.0)  As of PHP 5 this constant 
  21461.          returns the class name as it was declared (case-sensitive).  In PHP
  21462.          4 its value is always lowercased.
  21463.         </TD
  21464. ></TR
  21465. ><TR
  21466. ><TD
  21467. ><TT
  21468. CLASS="constant"
  21469. ><B
  21470. >__METHOD__</B
  21471. ></TT
  21472. ></TD
  21473. ><TD
  21474. >          The class method name. (Added in PHP 5.0.0)  The method name is
  21475.          returned as it was declared (case-sensitive).
  21476.         </TD
  21477. ></TR
  21478. ></TBODY
  21479. ></TABLE
  21480. ></DIV
  21481. >
  21482.    </P
  21483. ><P
  21484. >     See also 
  21485.     <A
  21486. HREF="#function.get-class"
  21487. ><B
  21488. CLASS="function"
  21489. >get_class()</B
  21490. ></A
  21491. >,
  21492.     <A
  21493. HREF="#function.get-object-vars"
  21494. ><B
  21495. CLASS="function"
  21496. >get_object_vars()</B
  21497. ></A
  21498. >,
  21499.     <A
  21500. HREF="#function.file-exists"
  21501. ><B
  21502. CLASS="function"
  21503. >file_exists()</B
  21504. ></A
  21505. > and
  21506.     <A
  21507. HREF="#function.function-exists"
  21508. ><B
  21509. CLASS="function"
  21510. >function_exists()</B
  21511. ></A
  21512. >.
  21513.    </P
  21514. ></DIV
  21515. ></DIV
  21516. ><DIV
  21517. CLASS="chapter"
  21518. ><HR><H1
  21519. ><A
  21520. NAME="language.expressions"
  21521. >Chapter 14. Expressions</A
  21522. ></H1
  21523. ><P
  21524. >     Expressions are the most important building stones of PHP.  In PHP,
  21525.     almost anything you write is an expression.  The simplest yet
  21526.     most accurate way to define an expression is "anything that has a
  21527.     value".
  21528.    </P
  21529. ><P
  21530. >     The most basic forms of expressions are constants and variables.
  21531.     When you type "$a = 5", you're assigning '5' into $a.  '5', obviously,
  21532.     has the value 5, or in other words '5' is an expression with the
  21533.     value of 5 (in this case, '5' is an integer constant).
  21534.    </P
  21535. ><P
  21536. >     After this assignment, you'd expect $a's value to be 5 as
  21537.     well, so if you wrote $b = $a, you'd expect it to behave just as
  21538.     if you wrote $b = 5.  In other words, $a is an expression with the
  21539.     value of 5 as well.  If everything works right, this is exactly
  21540.     what will happen.
  21541.    </P
  21542. ><P
  21543. >     Slightly more complex examples for expressions are functions.  For
  21544.     instance, consider the following function:
  21545.     <DIV
  21546. CLASS="informalexample"
  21547. ><P
  21548. ></P
  21549. ><A
  21550. NAME="AEN3833"
  21551. ></A
  21552. ><TABLE
  21553. BORDER="0"
  21554. BGCOLOR="#E0E0E0"
  21555. CELLPADDING="5"
  21556. ><TR
  21557. ><TD
  21558. ><PRE
  21559. CLASS="php"
  21560. ><?php
  21561. function foo ()
  21562. {
  21563.     return 5;
  21564. }
  21565. ?></PRE
  21566. ></TD
  21567. ></TR
  21568. ></TABLE
  21569. ><P
  21570. ></P
  21571. ></DIV
  21572. >
  21573.    </P
  21574. ><P
  21575. >     Assuming you're familiar with the concept of functions (if you're
  21576.     not, take a look at the chapter about <A
  21577. HREF="#language.functions"
  21578. >functions</A
  21579. >), you'd assume
  21580.     that typing <VAR
  21581. CLASS="literal"
  21582. >$c = foo()</VAR
  21583. > is essentially just like
  21584.     writing <VAR
  21585. CLASS="literal"
  21586. >$c = 5</VAR
  21587. >, and you're right.  Functions
  21588.     are expressions with the value of their return value.  Since foo()
  21589.     returns 5, the value of the expression 'foo()' is 5.  Usually
  21590.     functions don't just return a static value but compute something.
  21591.    </P
  21592. ><P
  21593. >     Of course, values in PHP don't have to be integers, and very often
  21594.     they aren't.  PHP supports four scalar value types: <A
  21595. HREF="#language.types.integer"
  21596. ><B
  21597. CLASS="type"
  21598. >integer</B
  21599. ></A
  21600. >
  21601.     values, floating point values (<A
  21602. HREF="#language.types.float"
  21603. ><B
  21604. CLASS="type"
  21605. >float</B
  21606. ></A
  21607. >), <A
  21608. HREF="#language.types.string"
  21609. ><B
  21610. CLASS="type"
  21611. >string</B
  21612. ></A
  21613. >
  21614.     values and <A
  21615. HREF="#language.types.boolean"
  21616. ><B
  21617. CLASS="type"
  21618. >boolean</B
  21619. ></A
  21620. > values (scalar values are values that you
  21621.     can't 'break' into smaller pieces, unlike arrays, for instance). PHP also 
  21622.     supports two composite (non-scalar) types: arrays and objects. Each of
  21623.     these value types can be assigned into variables or returned from functions.
  21624.    </P
  21625. ><P
  21626. >     PHP takes expressions much further, in the same way many other languages
  21627.     do.  PHP is an expression-oriented language, in the
  21628.     sense that almost everything is an expression.  Consider the
  21629.     example we've already dealt with, '$a = 5'.  It's easy to see that
  21630.     there are two values involved here, the value of the integer
  21631.     constant '5', and the value of $a which is being updated to 5 as
  21632.     well.  But the truth is that there's one additional value involved
  21633.     here, and that's the value of the assignment itself.  The
  21634.     assignment itself evaluates to the assigned value, in this case 5.
  21635.     In practice, it means that '$a = 5', regardless of what it does,
  21636.     is an expression with the value 5.  Thus, writing something like
  21637.     '$b = ($a = 5)' is like writing '$a = 5; $b = 5;' (a semicolon
  21638.     marks the end of a statement).  Since assignments are parsed in a
  21639.     right to left order, you can also write '$b = $a = 5'.
  21640.    </P
  21641. ><P
  21642. >     Another good example of expression orientation is pre- and
  21643.     post-increment and decrement.  Users of PHP and many other
  21644.     languages may be familiar with the notation of variable++ and
  21645.     variable--.  These are <A
  21646. HREF="#language.operators.increment"
  21647. >     increment and decrement operators</A
  21648. >.  In
  21649.     PHP/FI 2, the statement '$a++' has no value (is not an
  21650.     expression), and thus you can't assign it or use it in any way.
  21651.     PHP enhances the increment/decrement capabilities by making
  21652.     these expressions as well, like in C.  In PHP, like in C, there
  21653.     are two types of increment - pre-increment and post-increment.
  21654.     Both pre-increment and post-increment essentially increment the
  21655.     variable, and the effect on the variable is identical.  The
  21656.     difference is with the value of the increment expression.
  21657.     Pre-increment, which is written '++$variable', evaluates to the
  21658.     incremented value (PHP increments the variable before reading its
  21659.     value, thus the name 'pre-increment').  Post-increment, which is
  21660.     written '$variable++' evaluates to the original value of
  21661.     $variable, before it was incremented (PHP increments the variable
  21662.     after reading its value, thus the name 'post-increment').
  21663.    </P
  21664. ><P
  21665. >     A very common type of expressions are <A
  21666. HREF="#language.operators.comparison"
  21667. >comparison</A
  21668. >
  21669.     expressions. These expressions evaluate to either  <TT
  21670. CLASS="constant"
  21671. ><B
  21672. >FALSE</B
  21673. ></TT
  21674. > or <TT
  21675. CLASS="constant"
  21676. ><B
  21677. >TRUE</B
  21678. ></TT
  21679. >. PHP
  21680.     supports > (bigger than), >= (bigger than or equal to), == (equal),
  21681.     != (not equal), < (smaller than) and <= (smaller than or equal to).
  21682.     The language also supports a set of strict equivalence operators: ===
  21683.     (equal to and same type) and !== (not equal to or not same type).
  21684.     These expressions are most commonly used inside conditional execution,
  21685.     such as <VAR
  21686. CLASS="literal"
  21687. >if</VAR
  21688. > statements.
  21689.    </P
  21690. ><P
  21691. >     The last example of expressions we'll deal with here is combined
  21692.     operator-assignment expressions.  You already know that if you
  21693.     want to increment $a by 1, you can simply write '$a++' or '++$a'.
  21694.     But what if you want to add more than one to it, for instance 3?
  21695.     You could write '$a++' multiple times, but this is obviously not a
  21696.     very efficient or comfortable way.  A much more common practice is
  21697.     to write '$a = $a + 3'.  '$a + 3' evaluates to the value of $a
  21698.     plus 3, and is assigned back into $a, which results in
  21699.     incrementing $a by 3.  In PHP, as in several other languages
  21700.     like C, you can write this in a shorter way, which with time would
  21701.     become clearer and quicker to understand as well.  Adding 3 to the
  21702.     current value of $a can be written '$a += 3'.  This means exactly
  21703.     "take the value of $a, add 3 to it, and assign it back into $a".
  21704.     In addition to being shorter and clearer, this also results in
  21705.     faster execution.  The value of '$a += 3', like the value of a
  21706.     regular assignment, is the assigned value.  Notice that it is NOT
  21707.     3, but the combined value of $a plus 3 (this is the value that's
  21708.     assigned into $a).  Any two-place operator can be used in this
  21709.     operator-assignment mode, for example '$a -= 5' (subtract 5 from
  21710.     the value of $a), '$b *= 7' (multiply the value of $b by 7), etc.
  21711.    </P
  21712. ><P
  21713. >     There is one more expression that may seem odd if you haven't seen
  21714.     it in other languages, the ternary conditional operator:
  21715.    </P
  21716. ><P
  21717. >     <DIV
  21718. CLASS="informalexample"
  21719. ><P
  21720. ></P
  21721. ><A
  21722. NAME="AEN3855"
  21723. ></A
  21724. ><TABLE
  21725. BORDER="0"
  21726. BGCOLOR="#E0E0E0"
  21727. CELLPADDING="5"
  21728. ><TR
  21729. ><TD
  21730. ><PRE
  21731. CLASS="php"
  21732. ><?php
  21733. $first ? $second : $third
  21734. ?></PRE
  21735. ></TD
  21736. ></TR
  21737. ></TABLE
  21738. ><P
  21739. ></P
  21740. ></DIV
  21741. >
  21742.    </P
  21743. ><P
  21744. >     If the value of the first subexpression is <TT
  21745. CLASS="constant"
  21746. ><B
  21747. >TRUE</B
  21748. ></TT
  21749. > (non-zero), then
  21750.     the second subexpression is evaluated, and that is the result of
  21751.     the conditional expression. Otherwise, the third subexpression is
  21752.     evaluated, and that is the value.
  21753.    </P
  21754. ><P
  21755. >     The following example should help you understand pre- and
  21756.     post-increment and expressions in general a bit better:
  21757.    </P
  21758. ><P
  21759. >     <DIV
  21760. CLASS="informalexample"
  21761. ><P
  21762. ></P
  21763. ><A
  21764. NAME="AEN3861"
  21765. ></A
  21766. ><TABLE
  21767. BORDER="0"
  21768. BGCOLOR="#E0E0E0"
  21769. CELLPADDING="5"
  21770. ><TR
  21771. ><TD
  21772. ><PRE
  21773. CLASS="php"
  21774. ><?php
  21775. function double($i)
  21776. {
  21777.     return $i*2;
  21778. }
  21779. $b = $a = 5;        /* assign the value five into the variable $a and $b */
  21780. $c = $a++;          /* post-increment, assign original value of $a 
  21781.                        (5) to $c */
  21782. $e = $d = ++$b;     /* pre-increment, assign the incremented value of 
  21783.                        $b (6) to $d and $e */
  21784.  
  21785. /* at this point, both $d and $e are equal to 6 */
  21786.  
  21787. $f = double($d++);  /* assign twice the value of $d before
  21788.                        the increment, 2*6 = 12 to $f */
  21789. $g = double(++$e);  /* assign twice the value of $e after
  21790.                        the increment, 2*7 = 14 to $g */
  21791. $h = $g += 10;      /* first, $g is incremented by 10 and ends with the 
  21792.                        value of 24. the value of the assignment (24) is 
  21793.                        then assigned into $h, and $h ends with the value 
  21794.                        of 24 as well. */
  21795. ?></PRE
  21796. ></TD
  21797. ></TR
  21798. ></TABLE
  21799. ><P
  21800. ></P
  21801. ></DIV
  21802. >
  21803.    </P
  21804. ><P
  21805. >     Some expressions can be considered as statements. In
  21806.     this case, a statement has the form of 'expr' ';' that is, an
  21807.     expression followed by a semicolon.  In '$b=$a=5;', $a=5 is a
  21808.     valid expression, but it's not a statement by itself.  '$b=$a=5;'
  21809.     however is a valid statement.
  21810.    </P
  21811. ><P
  21812. >     One last thing worth mentioning is the truth value of expressions.
  21813.     In many events, mainly in conditional execution and loops, you're
  21814.     not interested in the specific value of the expression, but only
  21815.     care about whether it means <TT
  21816. CLASS="constant"
  21817. ><B
  21818. >TRUE</B
  21819. ></TT
  21820. > or <TT
  21821. CLASS="constant"
  21822. ><B
  21823. >FALSE</B
  21824. ></TT
  21825. >.
  21826.     
  21827.     
  21828.     
  21829.     The constants <TT
  21830. CLASS="constant"
  21831. ><B
  21832. >TRUE</B
  21833. ></TT
  21834. > and <TT
  21835. CLASS="constant"
  21836. ><B
  21837. >FALSE</B
  21838. ></TT
  21839. > (case-insensitive) are the two 
  21840.     possible boolean values. When necessary, an expression is 
  21841.     automatically converted to boolean. See the 
  21842.     <A
  21843. HREF="#language.types.typecasting"
  21844. >section about
  21845.     type-casting</A
  21846. > for details about how.
  21847.    </P
  21848. ><P
  21849. >     PHP provides a full and powerful implementation of expressions, and
  21850.     documenting it entirely goes beyond the scope of this manual. The
  21851.     above examples should give you a good idea about what expressions
  21852.     are and how you can construct useful expressions. Throughout the
  21853.     rest of this manual we'll write <VAR
  21854. CLASS="varname"
  21855. >expr</VAR
  21856. >
  21857.     to indicate any valid PHP expression.
  21858.    </P
  21859. ></DIV
  21860. ><DIV
  21861. CLASS="chapter"
  21862. ><HR><H1
  21863. ><A
  21864. NAME="language.operators"
  21865. >Chapter 15. Operators</A
  21866. ></H1
  21867. ><P
  21868. >    An operator is something that you feed with one or more values (or
  21869.    expressions, in programming jargon) which yields another value (so that the
  21870.    construction itself becomes an expression). So you can think of functions
  21871.    or constructions that return a value (like print) as operators and those
  21872.    that return nothing (like echo) as any other thing.
  21873.   </P
  21874. ><P
  21875. >    There are three types of operators.  Firstly there is the unary operator which
  21876.    operates on only one value, for example ! (the negation operator) or ++
  21877.    (the increment operator). The second group are termed binary operators; this
  21878.    group contains most of the operators that PHP supports, and a list follows
  21879.    below in the section <A
  21880. HREF="#language.operators.precedence"
  21881. >Operator
  21882.    Precedence</A
  21883. >.
  21884.   </P
  21885. ><P
  21886. >    The third group is the ternary operator: ?:.  It should be used to select
  21887.    between two expressions depending on a third one, rather than to select two
  21888.    sentences or paths of execution. Surrounding ternary expressions with
  21889.    parentheses is a very good idea.
  21890.   </P
  21891. ><DIV
  21892. CLASS="sect1"
  21893. ><HR><H2
  21894. CLASS="sect1"
  21895. ><A
  21896. NAME="language.operators.precedence"
  21897. >Operator Precedence</A
  21898. ></H2
  21899. ><P
  21900. >     The precedence of an operator specifies how "tightly" it binds two
  21901.     expressions together. For example, in the expression <VAR
  21902. CLASS="literal"
  21903. >1 +
  21904.     5 * 3</VAR
  21905. >, the answer is <VAR
  21906. CLASS="literal"
  21907. >16</VAR
  21908. > and not
  21909.     <VAR
  21910. CLASS="literal"
  21911. >18</VAR
  21912. > because the multiplication ("*") operator
  21913.     has a higher precedence than the addition ("+") operator.
  21914.     Parentheses may be used to force precedence, if necessary. For
  21915.     instance: <VAR
  21916. CLASS="literal"
  21917. >(1 + 5) * 3</VAR
  21918. > evaluates to
  21919.     <VAR
  21920. CLASS="literal"
  21921. >18</VAR
  21922. >. If operator precedence is equal, left to right 
  21923.     associativity is used.
  21924.    </P
  21925. ><P
  21926. >     The following table lists the precedence of operators with the
  21927.     highest-precedence operators listed at the top of the table. Operators
  21928.     on the same line have equal precedence, in which case their
  21929.     associativity decides which order to evaluate them in.
  21930.     <DIV
  21931. CLASS="table"
  21932. ><A
  21933. NAME="AEN3887"
  21934. ></A
  21935. ><P
  21936. ><B
  21937. >Table 15-1. Operator Precedence</B
  21938. ></P
  21939. ><TABLE
  21940. BORDER="1"
  21941. CLASS="CALSTABLE"
  21942. ><COL><COL><THEAD
  21943. ><TR
  21944. ><TH
  21945. >Associativity</TH
  21946. ><TH
  21947. >Operators</TH
  21948. ></TR
  21949. ></THEAD
  21950. ><TBODY
  21951. ><TR
  21952. ><TD
  21953. >non-associative</TD
  21954. ><TD
  21955. >new</TD
  21956. ></TR
  21957. ><TR
  21958. ><TD
  21959. >right</TD
  21960. ><TD
  21961. >[</TD
  21962. ></TR
  21963. ><TR
  21964. ><TD
  21965. >non-associative</TD
  21966. ><TD
  21967. >++ --</TD
  21968. ></TR
  21969. ><TR
  21970. ><TD
  21971. >non-associative</TD
  21972. ><TD
  21973. >! ~ - (int) (float) (string) (array) (object) @</TD
  21974. ></TR
  21975. ><TR
  21976. ><TD
  21977. >left</TD
  21978. ><TD
  21979. >* / %</TD
  21980. ></TR
  21981. ><TR
  21982. ><TD
  21983. >left</TD
  21984. ><TD
  21985. >+ - .</TD
  21986. ></TR
  21987. ><TR
  21988. ><TD
  21989. >left</TD
  21990. ><TD
  21991. ><< >></TD
  21992. ></TR
  21993. ><TR
  21994. ><TD
  21995. >non-associative</TD
  21996. ><TD
  21997. >< <= > >=</TD
  21998. ></TR
  21999. ><TR
  22000. ><TD
  22001. >non-associative</TD
  22002. ><TD
  22003. >== != === !==</TD
  22004. ></TR
  22005. ><TR
  22006. ><TD
  22007. >left</TD
  22008. ><TD
  22009. >&</TD
  22010. ></TR
  22011. ><TR
  22012. ><TD
  22013. >left</TD
  22014. ><TD
  22015. >^</TD
  22016. ></TR
  22017. ><TR
  22018. ><TD
  22019. >left</TD
  22020. ><TD
  22021. >|</TD
  22022. ></TR
  22023. ><TR
  22024. ><TD
  22025. >left</TD
  22026. ><TD
  22027. >&&</TD
  22028. ></TR
  22029. ><TR
  22030. ><TD
  22031. >left</TD
  22032. ><TD
  22033. >||</TD
  22034. ></TR
  22035. ><TR
  22036. ><TD
  22037. >left</TD
  22038. ><TD
  22039. >? :</TD
  22040. ></TR
  22041. ><TR
  22042. ><TD
  22043. >right</TD
  22044. ><TD
  22045. >          = += -= *= /= .= %= &= |= ^= <<= >>=
  22046.         </TD
  22047. ></TR
  22048. ><TR
  22049. ><TD
  22050. >left</TD
  22051. ><TD
  22052. >and</TD
  22053. ></TR
  22054. ><TR
  22055. ><TD
  22056. >left</TD
  22057. ><TD
  22058. >xor</TD
  22059. ></TR
  22060. ><TR
  22061. ><TD
  22062. >left</TD
  22063. ><TD
  22064. >or</TD
  22065. ></TR
  22066. ><TR
  22067. ><TD
  22068. >left</TD
  22069. ><TD
  22070. >,</TD
  22071. ></TR
  22072. ></TBODY
  22073. ></TABLE
  22074. ></DIV
  22075. >
  22076.    </P
  22077. ><P
  22078. >     Left associativity means that the expression is evaluated from left to right,
  22079.     right associativity means the opposite.
  22080.     <TABLE
  22081. WIDTH="100%"
  22082. BORDER="0"
  22083. CELLPADDING="0"
  22084. CELLSPACING="0"
  22085. CLASS="EXAMPLE"
  22086. ><TR
  22087. ><TD
  22088. ><DIV
  22089. CLASS="example"
  22090. ><A
  22091. NAME="AEN3956"
  22092. ></A
  22093. ><P
  22094. ><B
  22095. >Example 15-1. Associativity</B
  22096. ></P
  22097. ><TABLE
  22098. BORDER="0"
  22099. BGCOLOR="#E0E0E0"
  22100. CELLPADDING="5"
  22101. ><TR
  22102. ><TD
  22103. ><PRE
  22104. CLASS="php"
  22105. ><?php
  22106. $a = 3 * 3 % 5; // (3 * 3) % 5 = 4
  22107. $a = true ? 0 : true ? 1 : 2; // (true ? 0 : true) ? 1 : 2 = 2
  22108.  
  22109. $a = 1;
  22110. $b = 2;
  22111. $a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
  22112. ?></PRE
  22113. ></TD
  22114. ></TR
  22115. ></TABLE
  22116. ></DIV
  22117. ></TD
  22118. ></TR
  22119. ></TABLE
  22120. >
  22121.     Use parentheses to increase readability of the code.
  22122.    </P
  22123. ><DIV
  22124. CLASS="note"
  22125. ><BLOCKQUOTE
  22126. CLASS="note"
  22127. ><P
  22128. ><B
  22129. >Note: </B
  22130. >
  22131.      Although <VAR
  22132. CLASS="literal"
  22133. >!</VAR
  22134. > has a higher precedence than
  22135.      <VAR
  22136. CLASS="literal"
  22137. >=</VAR
  22138. >, PHP will still allow expressions
  22139.      similar to the following: <VAR
  22140. CLASS="literal"
  22141. >if (!$a = foo())</VAR
  22142. >,
  22143.      in which case the output from <VAR
  22144. CLASS="literal"
  22145. >foo()</VAR
  22146. > is
  22147.      put into <VAR
  22148. CLASS="varname"
  22149. >$a</VAR
  22150. >.
  22151.     </P
  22152. ></BLOCKQUOTE
  22153. ></DIV
  22154. ></DIV
  22155. ><DIV
  22156. CLASS="sect1"
  22157. ><HR><H2
  22158. CLASS="sect1"
  22159. ><A
  22160. NAME="language.operators.arithmetic"
  22161. >Arithmetic Operators</A
  22162. ></H2
  22163. ><P
  22164. >     Remember basic arithmetic from school? These work just
  22165.     like those.
  22166.    </P
  22167. ><DIV
  22168. CLASS="table"
  22169. ><A
  22170. NAME="AEN3969"
  22171. ></A
  22172. ><P
  22173. ><B
  22174. >Table 15-2. Arithmetic Operators</B
  22175. ></P
  22176. ><TABLE
  22177. BORDER="1"
  22178. CLASS="CALSTABLE"
  22179. ><COL><COL><COL><THEAD
  22180. ><TR
  22181. ><TH
  22182. >Example</TH
  22183. ><TH
  22184. >Name</TH
  22185. ><TH
  22186. >Result</TH
  22187. ></TR
  22188. ></THEAD
  22189. ><TBODY
  22190. ><TR
  22191. ><TD
  22192. >-$a</TD
  22193. ><TD
  22194. >Negation</TD
  22195. ><TD
  22196. >Opposite of $a.</TD
  22197. ></TR
  22198. ><TR
  22199. ><TD
  22200. >$a + $b</TD
  22201. ><TD
  22202. >Addition</TD
  22203. ><TD
  22204. >Sum of $a and $b.</TD
  22205. ></TR
  22206. ><TR
  22207. ><TD
  22208. >$a - $b</TD
  22209. ><TD
  22210. >Subtraction</TD
  22211. ><TD
  22212. >Difference of $a and $b.</TD
  22213. ></TR
  22214. ><TR
  22215. ><TD
  22216. >$a * $b</TD
  22217. ><TD
  22218. >Multiplication</TD
  22219. ><TD
  22220. >Product of $a and $b.</TD
  22221. ></TR
  22222. ><TR
  22223. ><TD
  22224. >$a / $b</TD
  22225. ><TD
  22226. >Division</TD
  22227. ><TD
  22228. >Quotient of $a and $b.</TD
  22229. ></TR
  22230. ><TR
  22231. ><TD
  22232. >$a % $b</TD
  22233. ><TD
  22234. >Modulus</TD
  22235. ><TD
  22236. >Remainder of $a divided by $b.</TD
  22237. ></TR
  22238. ></TBODY
  22239. ></TABLE
  22240. ></DIV
  22241. ><P
  22242. >     The division operator ("/") returns a float value anytime,
  22243.     even if the two operands are integers (or strings that get
  22244.     converted to integers).
  22245.    </P
  22246. ><DIV
  22247. CLASS="note"
  22248. ><BLOCKQUOTE
  22249. CLASS="note"
  22250. ><P
  22251. ><B
  22252. >Note: </B
  22253. >
  22254.      Remainder <VAR
  22255. CLASS="literal"
  22256. >$a % $b</VAR
  22257. > is negative for negative
  22258.      <VAR
  22259. CLASS="literal"
  22260. >$a</VAR
  22261. >.
  22262.     </P
  22263. ></BLOCKQUOTE
  22264. ></DIV
  22265. ><P
  22266. >     See also the manual page on 
  22267.     <A
  22268. HREF="#ref.math"
  22269. >Math functions</A
  22270. >. 
  22271.    </P
  22272. ></DIV
  22273. ><DIV
  22274. CLASS="sect1"
  22275. ><HR><H2
  22276. CLASS="sect1"
  22277. ><A
  22278. NAME="language.operators.assignment"
  22279. >Assignment Operators</A
  22280. ></H2
  22281. ><P
  22282. >     The basic assignment operator is "=". Your first inclination might
  22283.     be to think of this as "equal to". Don't. It really means that the
  22284.     the left operand gets set to the value of the expression on the
  22285.     rights (that is, "gets set to").
  22286.    </P
  22287. ><P
  22288. >     The value of an assignment expression is the value assigned. That
  22289.     is, the value of "$a = 3" is 3. This allows you to do some tricky
  22290.     things: 
  22291.     <DIV
  22292. CLASS="informalexample"
  22293. ><P
  22294. ></P
  22295. ><A
  22296. NAME="AEN4013"
  22297. ></A
  22298. ><TABLE
  22299. BORDER="0"
  22300. BGCOLOR="#E0E0E0"
  22301. CELLPADDING="5"
  22302. ><TR
  22303. ><TD
  22304. ><PRE
  22305. CLASS="php"
  22306. ><?php
  22307.  
  22308. $a = ($b = 4) + 5; // $a is equal to 9 now, and $b has been set to 4.
  22309.  
  22310. ?></PRE
  22311. ></TD
  22312. ></TR
  22313. ></TABLE
  22314. ><P
  22315. ></P
  22316. ></DIV
  22317. >
  22318.    </P
  22319. ><P
  22320. >     In addition to the basic assignment operator, there are "combined
  22321.     operators" for all of the <A
  22322. HREF="#language.operators"
  22323. >binary
  22324.     arithmetic</A
  22325. > and string operators that allow you to use a value in an
  22326.     expression and then set its value to the result of that expression. For
  22327.     example:
  22328.     <DIV
  22329. CLASS="informalexample"
  22330. ><P
  22331. ></P
  22332. ><A
  22333. NAME="AEN4017"
  22334. ></A
  22335. ><TABLE
  22336. BORDER="0"
  22337. BGCOLOR="#E0E0E0"
  22338. CELLPADDING="5"
  22339. ><TR
  22340. ><TD
  22341. ><PRE
  22342. CLASS="php"
  22343. ><?php
  22344.  
  22345. $a = 3;
  22346. $a += 5; // sets $a to 8, as if we had said: $a = $a + 5;
  22347. $b = "Hello ";
  22348. $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
  22349.  
  22350. ?></PRE
  22351. ></TD
  22352. ></TR
  22353. ></TABLE
  22354. ><P
  22355. ></P
  22356. ></DIV
  22357. >
  22358.    </P
  22359. ><P
  22360. >     Note that the assignment copies the original variable to the new
  22361.     one (assignment by value), so changes to one will not affect the
  22362.     other. This may also have relevance if you need to copy something
  22363.     like a large array inside a tight loop. Since PHP 4, assignment
  22364.     by reference has been supported, using the <SAMP
  22365. CLASS="computeroutput"
  22366. >$var =
  22367.     &$othervar;</SAMP
  22368. > syntax, but this is not possible
  22369.     in PHP 3. 'Assignment by reference' means that both variables end
  22370.     up pointing at the same data, and nothing is copied anywhere. 
  22371.     To learn more about references, please read <A
  22372. HREF="#language.references"
  22373. >References explained</A
  22374. >.
  22375.    </P
  22376. ></DIV
  22377. ><DIV
  22378. CLASS="sect1"
  22379. ><HR><H2
  22380. CLASS="sect1"
  22381. ><A
  22382. NAME="language.operators.bitwise"
  22383. >Bitwise Operators</A
  22384. ></H2
  22385. ><P
  22386. >     Bitwise operators allow you to turn specific bits within an
  22387.     integer on or off. If both the left- and right-hand parameters are
  22388.     strings, the bitwise operator will operate on the characters' ASCII
  22389.     values.
  22390.    </P
  22391. ><P
  22392. >     <DIV
  22393. CLASS="informalexample"
  22394. ><P
  22395. ></P
  22396. ><A
  22397. NAME="AEN4026"
  22398. ></A
  22399. ><TABLE
  22400. BORDER="0"
  22401. BGCOLOR="#E0E0E0"
  22402. CELLPADDING="5"
  22403. ><TR
  22404. ><TD
  22405. ><PRE
  22406. CLASS="php"
  22407. ><?php
  22408. echo 12 ^ 9; // Outputs '5'
  22409.  
  22410. echo "12" ^ "9"; // Outputs the Backspace character (ascii 8)
  22411.                  // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8
  22412.  
  22413. echo "hallo" ^ "hello"; // Outputs the ascii values #0 #4 #0 #0 #0
  22414.                         // 'a' ^ 'e' = #4
  22415. ?></PRE
  22416. ></TD
  22417. ></TR
  22418. ></TABLE
  22419. ><P
  22420. ></P
  22421. ></DIV
  22422. > 
  22423.    </P
  22424. ><DIV
  22425. CLASS="table"
  22426. ><A
  22427. NAME="AEN4028"
  22428. ></A
  22429. ><P
  22430. ><B
  22431. >Table 15-3. Bitwise Operators</B
  22432. ></P
  22433. ><TABLE
  22434. BORDER="1"
  22435. CLASS="CALSTABLE"
  22436. ><COL><COL><COL><THEAD
  22437. ><TR
  22438. ><TH
  22439. >Example</TH
  22440. ><TH
  22441. >Name</TH
  22442. ><TH
  22443. >Result</TH
  22444. ></TR
  22445. ></THEAD
  22446. ><TBODY
  22447. ><TR
  22448. ><TD
  22449. >$a & $b</TD
  22450. ><TD
  22451. >And</TD
  22452. ><TD
  22453. >Bits that are set in both $a and $b are set.</TD
  22454. ></TR
  22455. ><TR
  22456. ><TD
  22457. >$a | $b</TD
  22458. ><TD
  22459. >Or</TD
  22460. ><TD
  22461. >Bits that are set in either $a or $b are set.</TD
  22462. ></TR
  22463. ><TR
  22464. ><TD
  22465. >$a ^ $b</TD
  22466. ><TD
  22467. >Xor</TD
  22468. ><TD
  22469. >         Bits that are set in $a or $b but not both are set.
  22470.        </TD
  22471. ></TR
  22472. ><TR
  22473. ><TD
  22474. >~ $a</TD
  22475. ><TD
  22476. >Not</TD
  22477. ><TD
  22478. >         Bits that are set in $a are not set, and vice versa.
  22479.        </TD
  22480. ></TR
  22481. ><TR
  22482. ><TD
  22483. >$a << $b</TD
  22484. ><TD
  22485. >Shift left</TD
  22486. ><TD
  22487. >         Shift the bits of $a $b steps to the left (each step means
  22488.         "multiply by two")
  22489.        </TD
  22490. ></TR
  22491. ><TR
  22492. ><TD
  22493. >$a >> $b</TD
  22494. ><TD
  22495. >Shift right</TD
  22496. ><TD
  22497. >         Shift the bits of $a $b steps to the right (each step means
  22498.         "divide by two")
  22499.        </TD
  22500. ></TR
  22501. ></TBODY
  22502. ></TABLE
  22503. ></DIV
  22504. ><DIV
  22505. CLASS="warning"
  22506. ><P
  22507. ></P
  22508. ><TABLE
  22509. CLASS="warning"
  22510. BORDER="1"
  22511. WIDTH="100%"
  22512. ><TR
  22513. ><TD
  22514. ALIGN="CENTER"
  22515. ><B
  22516. >Warning</B
  22517. ></TD
  22518. ></TR
  22519. ><TR
  22520. ><TD
  22521. ALIGN="LEFT"
  22522. ><P
  22523. >      Don't right shift for more than 32 bits on 32 bits systems. Don't left shift
  22524.      in case it results to number longer than 32 bits.
  22525.     </P
  22526. ></TD
  22527. ></TR
  22528. ></TABLE
  22529. ></DIV
  22530. ></DIV
  22531. ><DIV
  22532. CLASS="sect1"
  22533. ><HR><H2
  22534. CLASS="sect1"
  22535. ><A
  22536. NAME="language.operators.comparison"
  22537. >Comparison Operators</A
  22538. ></H2
  22539. ><P
  22540. >     Comparison operators, as their name implies, allow you to compare
  22541.     two values.  You may also be interested in viewing
  22542.     <A
  22543. HREF="#types.comparisons"
  22544. >the type comparison tables</A
  22545. >, 
  22546.     as they show examples of various type related comparisons.
  22547.    </P
  22548. ><DIV
  22549. CLASS="table"
  22550. ><A
  22551. NAME="AEN4067"
  22552. ></A
  22553. ><P
  22554. ><B
  22555. >Table 15-4. Comparison Operators</B
  22556. ></P
  22557. ><TABLE
  22558. BORDER="1"
  22559. CLASS="CALSTABLE"
  22560. ><COL><COL><COL><THEAD
  22561. ><TR
  22562. ><TH
  22563. >Example</TH
  22564. ><TH
  22565. >Name</TH
  22566. ><TH
  22567. >Result</TH
  22568. ></TR
  22569. ></THEAD
  22570. ><TBODY
  22571. ><TR
  22572. ><TD
  22573. >$a == $b</TD
  22574. ><TD
  22575. >Equal</TD
  22576. ><TD
  22577. ><TT
  22578. CLASS="constant"
  22579. ><B
  22580. >TRUE</B
  22581. ></TT
  22582. > if $a is equal to $b.</TD
  22583. ></TR
  22584. ><TR
  22585. ><TD
  22586. >$a === $b</TD
  22587. ><TD
  22588. >Identical</TD
  22589. ><TD
  22590. >         <TT
  22591. CLASS="constant"
  22592. ><B
  22593. >TRUE</B
  22594. ></TT
  22595. > if $a is equal to $b, and they are of the same
  22596.         type. (introduced in PHP 4)
  22597.        </TD
  22598. ></TR
  22599. ><TR
  22600. ><TD
  22601. >$a != $b</TD
  22602. ><TD
  22603. >Not equal</TD
  22604. ><TD
  22605. ><TT
  22606. CLASS="constant"
  22607. ><B
  22608. >TRUE</B
  22609. ></TT
  22610. > if $a is not equal to $b.</TD
  22611. ></TR
  22612. ><TR
  22613. ><TD
  22614. >$a <> $b</TD
  22615. ><TD
  22616. >Not equal</TD
  22617. ><TD
  22618. ><TT
  22619. CLASS="constant"
  22620. ><B
  22621. >TRUE</B
  22622. ></TT
  22623. > if $a is not equal to $b.</TD
  22624. ></TR
  22625. ><TR
  22626. ><TD
  22627. >$a !== $b</TD
  22628. ><TD
  22629. >Not identical</TD
  22630. ><TD
  22631. >         <TT
  22632. CLASS="constant"
  22633. ><B
  22634. >TRUE</B
  22635. ></TT
  22636. > if $a is not equal to $b, or they are not of the same
  22637.         type. (introduced in PHP 4)
  22638.        </TD
  22639. ></TR
  22640. ><TR
  22641. ><TD
  22642. >$a < $b</TD
  22643. ><TD
  22644. >Less than</TD
  22645. ><TD
  22646. ><TT
  22647. CLASS="constant"
  22648. ><B
  22649. >TRUE</B
  22650. ></TT
  22651. > if $a is strictly less than $b.</TD
  22652. ></TR
  22653. ><TR
  22654. ><TD
  22655. >$a > $b</TD
  22656. ><TD
  22657. >Greater than</TD
  22658. ><TD
  22659. ><TT
  22660. CLASS="constant"
  22661. ><B
  22662. >TRUE</B
  22663. ></TT
  22664. > if $a is strictly greater than $b.</TD
  22665. ></TR
  22666. ><TR
  22667. ><TD
  22668. >$a <= $b</TD
  22669. ><TD
  22670. >Less than or equal to </TD
  22671. ><TD
  22672. ><TT
  22673. CLASS="constant"
  22674. ><B
  22675. >TRUE</B
  22676. ></TT
  22677. > if $a is less than or equal to $b.</TD
  22678. ></TR
  22679. ><TR
  22680. ><TD
  22681. >$a >= $b</TD
  22682. ><TD
  22683. >Greater than or equal to </TD
  22684. ><TD
  22685. ><TT
  22686. CLASS="constant"
  22687. ><B
  22688. >TRUE</B
  22689. ></TT
  22690. > if $a is greater than or equal to $b.</TD
  22691. ></TR
  22692. ></TBODY
  22693. ></TABLE
  22694. ></DIV
  22695. ><P
  22696. >     If you compare an integer with a string, the string is
  22697.     <A
  22698. HREF="#language.types.string.conversion"
  22699. >converted to a number</A
  22700. >.
  22701.     If you compare two numerical strings, they are compared as integers. These
  22702.     rules also apply to the
  22703.     <A
  22704. HREF="#control-structures.switch"
  22705. >switch</A
  22706. > statement.
  22707.     <DIV
  22708. CLASS="informalexample"
  22709. ><P
  22710. ></P
  22711. ><A
  22712. NAME="AEN4124"
  22713. ></A
  22714. ><TABLE
  22715. BORDER="0"
  22716. BGCOLOR="#E0E0E0"
  22717. CELLPADDING="5"
  22718. ><TR
  22719. ><TD
  22720. ><PRE
  22721. CLASS="php"
  22722. ><?php
  22723. var_dump(0 == "a"); // 0 == 0 -> true
  22724. var_dump("1" == "01"); // 1 == 1 -> true
  22725.  
  22726. switch ("a") {
  22727. case 0:
  22728.     echo "0";
  22729.     break;
  22730. case "a": // never reached because "a" is already matched with 0
  22731.     echo "a";
  22732.     break;
  22733. }
  22734. ?></PRE
  22735. ></TD
  22736. ></TR
  22737. ></TABLE
  22738. ><P
  22739. ></P
  22740. ></DIV
  22741. > 
  22742.    </P
  22743. ><P
  22744. >     Another conditional operator is the "?:" (or ternary) operator.
  22745.     <DIV
  22746. CLASS="informalexample"
  22747. ><P
  22748. ></P
  22749. ><A
  22750. NAME="AEN4127"
  22751. ></A
  22752. ><TABLE
  22753. BORDER="0"
  22754. BGCOLOR="#E0E0E0"
  22755. CELLPADDING="5"
  22756. ><TR
  22757. ><TD
  22758. ><PRE
  22759. CLASS="php"
  22760. ><?php
  22761. // Example usage for: Ternary Operator
  22762. $action = (empty($_POST['action'])) ? 'default' : $_POST['action'];
  22763.  
  22764. // The above is identical to this if/else statement
  22765. if (empty($_POST['action'])) {
  22766.     $action = 'default';
  22767. } else {
  22768.     $action = $_POST['action'];
  22769. }
  22770. ?></PRE
  22771. ></TD
  22772. ></TR
  22773. ></TABLE
  22774. ><P
  22775. ></P
  22776. ></DIV
  22777. > 
  22778.     The expression <VAR
  22779. CLASS="literal"
  22780. >(expr1) ? (expr2) : (expr3)</VAR
  22781. >
  22782.     evaluates to <VAR
  22783. CLASS="replaceable"
  22784. >expr2</VAR
  22785. > if
  22786.     <VAR
  22787. CLASS="replaceable"
  22788. >expr1</VAR
  22789. > evaluates to <TT
  22790. CLASS="constant"
  22791. ><B
  22792. >TRUE</B
  22793. ></TT
  22794. >, and
  22795.     <VAR
  22796. CLASS="replaceable"
  22797. >expr3</VAR
  22798. > if
  22799.     <VAR
  22800. CLASS="replaceable"
  22801. >expr1</VAR
  22802. > evaluates to <TT
  22803. CLASS="constant"
  22804. ><B
  22805. >FALSE</B
  22806. ></TT
  22807. >.
  22808.    </P
  22809. ><P
  22810. >     See also <A
  22811. HREF="#function.strcasecmp"
  22812. ><B
  22813. CLASS="function"
  22814. >strcasecmp()</B
  22815. ></A
  22816. >,
  22817.     <A
  22818. HREF="#function.strcmp"
  22819. ><B
  22820. CLASS="function"
  22821. >strcmp()</B
  22822. ></A
  22823. >,
  22824.     <A
  22825. HREF="#language.operators.array"
  22826. >Array operators</A
  22827. >,
  22828.     and the manual section on
  22829.     <A
  22830. HREF="#language.types"
  22831. >Types</A
  22832. >.
  22833.    </P
  22834. ></DIV
  22835. ><DIV
  22836. CLASS="sect1"
  22837. ><HR><H2
  22838. CLASS="sect1"
  22839. ><A
  22840. NAME="language.operators.errorcontrol"
  22841. >Error Control Operators</A
  22842. ></H2
  22843. ><P
  22844. >     PHP supports one error control operator: the at sign (@). When
  22845.     prepended to an expression in PHP, any error messages that might
  22846.     be generated by that expression will be ignored.
  22847.    </P
  22848. ><P
  22849. >     If the <A
  22850. HREF="#ini.track-errors"
  22851. ><VAR
  22852. CLASS="option"
  22853. >track_errors</VAR
  22854. ></A
  22855. >
  22856.     feature is enabled, any error message generated by the expression
  22857.     will be saved in the variable
  22858.     <A
  22859. HREF="#reserved.variables.phperrormsg"
  22860. >$php_errormsg</A
  22861. >.
  22862.     This variable will be overwritten on each error, so check early if you
  22863.     want to use it.
  22864.    </P
  22865. ><P
  22866. >     <DIV
  22867. CLASS="informalexample"
  22868. ><P
  22869. ></P
  22870. ><A
  22871. NAME="AEN4149"
  22872. ></A
  22873. ><TABLE
  22874. BORDER="0"
  22875. BGCOLOR="#E0E0E0"
  22876. CELLPADDING="5"
  22877. ><TR
  22878. ><TD
  22879. ><PRE
  22880. CLASS="php"
  22881. ><?php
  22882. /* Intentional file error */
  22883. $my_file = @file ('non_existent_file') or
  22884.     die ("Failed opening file: error was '$php_errormsg'");
  22885.  
  22886. // this works for any expression, not just functions:
  22887. $value = @$cache[$key]; 
  22888. // will not issue a notice if the index $key doesn't exist.
  22889.  
  22890. ?></PRE
  22891. ></TD
  22892. ></TR
  22893. ></TABLE
  22894. ><P
  22895. ></P
  22896. ></DIV
  22897. >
  22898.    </P
  22899. ><DIV
  22900. CLASS="note"
  22901. ><BLOCKQUOTE
  22902. CLASS="note"
  22903. ><P
  22904. ><B
  22905. >Note: </B
  22906. >
  22907.      The @-operator works only on
  22908.      <A
  22909. HREF="#language.expressions"
  22910. >expressions</A
  22911. >. A simple rule
  22912.      of thumb is: if you can take the value of something, you can prepend
  22913.      the @ operator to it. For instance, you can prepend it to variables,
  22914.      function and <A
  22915. HREF="#function.include"
  22916. ><B
  22917. CLASS="function"
  22918. >include()</B
  22919. ></A
  22920. > calls, constants, and
  22921.      so forth. You cannot prepend it to function or class definitions,
  22922.      or conditional structures such as <VAR
  22923. CLASS="literal"
  22924. >if</VAR
  22925. > and
  22926.      <VAR
  22927. CLASS="literal"
  22928. >foreach</VAR
  22929. >, and so forth.
  22930.     </P
  22931. ></BLOCKQUOTE
  22932. ></DIV
  22933. ><P
  22934. >     See also <A
  22935. HREF="#function.error-reporting"
  22936. ><B
  22937. CLASS="function"
  22938. >error_reporting()</B
  22939. ></A
  22940. > and the manual section for
  22941.     <A
  22942. HREF="#ref.errorfunc"
  22943. >Error Handling and Logging functions</A
  22944. >.
  22945.    </P
  22946. ><DIV
  22947. CLASS="note"
  22948. ><BLOCKQUOTE
  22949. CLASS="note"
  22950. ><P
  22951. ><B
  22952. >Note: </B
  22953. >
  22954.      The "@" error-control operator prefix will not disable messages
  22955.      that are the result of parse errors.
  22956.     </P
  22957. ></BLOCKQUOTE
  22958. ></DIV
  22959. ><DIV
  22960. CLASS="warning"
  22961. ><P
  22962. ></P
  22963. ><TABLE
  22964. CLASS="warning"
  22965. BORDER="1"
  22966. WIDTH="100%"
  22967. ><TR
  22968. ><TD
  22969. ALIGN="CENTER"
  22970. ><B
  22971. >Warning</B
  22972. ></TD
  22973. ></TR
  22974. ><TR
  22975. ><TD
  22976. ALIGN="LEFT"
  22977. ><P
  22978. >      Currently the "@" error-control operator prefix will even disable
  22979.      error reporting for critical errors that will terminate script
  22980.      execution. Among other things, this means that if you use "@" to
  22981.      suppress errors from a certain function and either it isn't
  22982.      available or has been mistyped, the script will die right there
  22983.      with no indication as to why.
  22984.     </P
  22985. ></TD
  22986. ></TR
  22987. ></TABLE
  22988. ></DIV
  22989. ></DIV
  22990. ><DIV
  22991. CLASS="sect1"
  22992. ><HR><H2
  22993. CLASS="sect1"
  22994. ><A
  22995. NAME="language.operators.execution"
  22996. >Execution Operators</A
  22997. ></H2
  22998. ><P
  22999. >     PHP supports one execution operator: backticks (``). Note that
  23000.     these are not single-quotes! PHP will attempt to execute the
  23001.     contents of the backticks as a shell command; the output will be
  23002.     returned (i.e., it won't simply be dumped to output; it can be
  23003.     assigned to a variable).  Use of the backtick operator is identical 
  23004.     to <A
  23005. HREF="#function.shell-exec"
  23006. ><B
  23007. CLASS="function"
  23008. >shell_exec()</B
  23009. ></A
  23010. >. 
  23011.     <DIV
  23012. CLASS="informalexample"
  23013. ><P
  23014. ></P
  23015. ><A
  23016. NAME="AEN4168"
  23017. ></A
  23018. ><TABLE
  23019. BORDER="0"
  23020. BGCOLOR="#E0E0E0"
  23021. CELLPADDING="5"
  23022. ><TR
  23023. ><TD
  23024. ><PRE
  23025. CLASS="php"
  23026. ><?php
  23027. $output = `ls -al`;
  23028. echo "<pre>$output</pre>";
  23029. ?></PRE
  23030. ></TD
  23031. ></TR
  23032. ></TABLE
  23033. ><P
  23034. ></P
  23035. ></DIV
  23036. >
  23037.    </P
  23038. ><DIV
  23039. CLASS="note"
  23040. ><BLOCKQUOTE
  23041. CLASS="note"
  23042. ><P
  23043. ><B
  23044. >Note: </B
  23045. >
  23046.      The backtick operator is disabled when <A
  23047. HREF="#ini.safe-mode"
  23048. >safe mode</A
  23049. > is enabled
  23050.      or <A
  23051. HREF="#function.shell-exec"
  23052. ><B
  23053. CLASS="function"
  23054. >shell_exec()</B
  23055. ></A
  23056. > is disabled.
  23057.     </P
  23058. ></BLOCKQUOTE
  23059. ></DIV
  23060. ><P
  23061. >     See also the manual section on <A
  23062. HREF="#ref.exec"
  23063. >Program
  23064.     Execution functions</A
  23065. >, <A
  23066. HREF="#function.popen"
  23067. ><B
  23068. CLASS="function"
  23069. >popen()</B
  23070. ></A
  23071. >
  23072.     <A
  23073. HREF="#function.proc-open"
  23074. ><B
  23075. CLASS="function"
  23076. >proc_open()</B
  23077. ></A
  23078. >, and
  23079.     <A
  23080. HREF="#features.commandline"
  23081. >Using PHP from the
  23082.     commandline</A
  23083. >.
  23084.    </P
  23085. ></DIV
  23086. ><DIV
  23087. CLASS="sect1"
  23088. ><HR><H2
  23089. CLASS="sect1"
  23090. ><A
  23091. NAME="language.operators.increment"
  23092. >Incrementing/Decrementing Operators</A
  23093. ></H2
  23094. ><P
  23095. >     PHP supports C-style pre- and post-increment and decrement
  23096.     operators.
  23097.    </P
  23098. ><DIV
  23099. CLASS="table"
  23100. ><A
  23101. NAME="AEN4182"
  23102. ></A
  23103. ><P
  23104. ><B
  23105. >Table 15-5. Increment/decrement Operators</B
  23106. ></P
  23107. ><TABLE
  23108. BORDER="1"
  23109. CLASS="CALSTABLE"
  23110. ><COL><COL><COL><THEAD
  23111. ><TR
  23112. ><TH
  23113. >Example</TH
  23114. ><TH
  23115. >Name</TH
  23116. ><TH
  23117. >Effect</TH
  23118. ></TR
  23119. ></THEAD
  23120. ><TBODY
  23121. ><TR
  23122. ><TD
  23123. >++$a</TD
  23124. ><TD
  23125. >Pre-increment</TD
  23126. ><TD
  23127. >Increments $a by one, then returns $a.</TD
  23128. ></TR
  23129. ><TR
  23130. ><TD
  23131. >$a++</TD
  23132. ><TD
  23133. >Post-increment</TD
  23134. ><TD
  23135. >Returns $a, then increments $a by one.</TD
  23136. ></TR
  23137. ><TR
  23138. ><TD
  23139. >--$a</TD
  23140. ><TD
  23141. >Pre-decrement</TD
  23142. ><TD
  23143. >Decrements $a by one, then returns $a.</TD
  23144. ></TR
  23145. ><TR
  23146. ><TD
  23147. >$a--</TD
  23148. ><TD
  23149. >Post-decrement</TD
  23150. ><TD
  23151. >Returns $a, then decrements $a by one.</TD
  23152. ></TR
  23153. ></TBODY
  23154. ></TABLE
  23155. ></DIV
  23156. ><P
  23157. >     Here's a simple example script:
  23158.     <DIV
  23159. CLASS="informalexample"
  23160. ><P
  23161. ></P
  23162. ><A
  23163. NAME="AEN4208"
  23164. ></A
  23165. ><TABLE
  23166. BORDER="0"
  23167. BGCOLOR="#E0E0E0"
  23168. CELLPADDING="5"
  23169. ><TR
  23170. ><TD
  23171. ><PRE
  23172. CLASS="php"
  23173. ><?php
  23174. echo "<h3>Postincrement</h3>";
  23175. $a = 5;
  23176. echo "Should be 5: " . $a++ . "<br />\n";
  23177. echo "Should be 6: " . $a . "<br />\n";
  23178.  
  23179. echo "<h3>Preincrement</h3>";
  23180. $a = 5;
  23181. echo "Should be 6: " . ++$a . "<br />\n";
  23182. echo "Should be 6: " . $a . "<br />\n";
  23183.  
  23184. echo "<h3>Postdecrement</h3>";
  23185. $a = 5;
  23186. echo "Should be 5: " . $a-- . "<br />\n";
  23187. echo "Should be 4: " . $a . "<br />\n";
  23188.  
  23189. echo "<h3>Predecrement</h3>";
  23190. $a = 5;
  23191. echo "Should be 4: " . --$a . "<br />\n";
  23192. echo "Should be 4: " . $a . "<br />\n";
  23193. ?></PRE
  23194. ></TD
  23195. ></TR
  23196. ></TABLE
  23197. ><P
  23198. ></P
  23199. ></DIV
  23200. >
  23201.    </P
  23202. ><P
  23203. >     PHP follows Perl's convention when dealing with arithmetic operations
  23204.     on character variables and not C's.  For example, in Perl 'Z'+1 turns
  23205.     into 'AA', while in C 'Z'+1 turns into '[' ( ord('Z') == 90, ord('[') == 91 ).
  23206.     Note that character variables can be incremented but not decremented.
  23207.     <TABLE
  23208. WIDTH="100%"
  23209. BORDER="0"
  23210. CELLPADDING="0"
  23211. CELLSPACING="0"
  23212. CLASS="EXAMPLE"
  23213. ><TR
  23214. ><TD
  23215. ><DIV
  23216. CLASS="example"
  23217. ><A
  23218. NAME="AEN4211"
  23219. ></A
  23220. ><P
  23221. ><B
  23222. >Example 15-2. Arithmetic Operations on Character Variables</B
  23223. ></P
  23224. ><TABLE
  23225. BORDER="0"
  23226. BGCOLOR="#E0E0E0"
  23227. CELLPADDING="5"
  23228. ><TR
  23229. ><TD
  23230. ><PRE
  23231. CLASS="php"
  23232. ><?php
  23233. $i = 'W';
  23234. for($n=0; $n<6; $n++)
  23235.   echo ++$i . "\n";
  23236.  
  23237. /*
  23238.   Produces the output similar to the following:
  23239.  
  23240. X
  23241. Y
  23242. Z
  23243. AA
  23244. AB
  23245. AC
  23246.  
  23247. */
  23248. ?></PRE
  23249. ></TD
  23250. ></TR
  23251. ></TABLE
  23252. ></DIV
  23253. ></TD
  23254. ></TR
  23255. ></TABLE
  23256. >
  23257.    </P
  23258. ><P
  23259. >     Incrementing or decrementing booleans has no effect.
  23260.    </P
  23261. ></DIV
  23262. ><DIV
  23263. CLASS="sect1"
  23264. ><HR><H2
  23265. CLASS="sect1"
  23266. ><A
  23267. NAME="language.operators.logical"
  23268. >Logical Operators</A
  23269. ></H2
  23270. ><DIV
  23271. CLASS="table"
  23272. ><A
  23273. NAME="AEN4217"
  23274. ></A
  23275. ><P
  23276. ><B
  23277. >Table 15-6. Logical Operators</B
  23278. ></P
  23279. ><TABLE
  23280. BORDER="1"
  23281. CLASS="CALSTABLE"
  23282. ><COL><COL><COL><THEAD
  23283. ><TR
  23284. ><TH
  23285. >Example</TH
  23286. ><TH
  23287. >Name</TH
  23288. ><TH
  23289. >Result</TH
  23290. ></TR
  23291. ></THEAD
  23292. ><TBODY
  23293. ><TR
  23294. ><TD
  23295. >$a and $b</TD
  23296. ><TD
  23297. >And</TD
  23298. ><TD
  23299. ><TT
  23300. CLASS="constant"
  23301. ><B
  23302. >TRUE</B
  23303. ></TT
  23304. > if both $a and $b are <TT
  23305. CLASS="constant"
  23306. ><B
  23307. >TRUE</B
  23308. ></TT
  23309. >.</TD
  23310. ></TR
  23311. ><TR
  23312. ><TD
  23313. >$a or $b</TD
  23314. ><TD
  23315. >Or</TD
  23316. ><TD
  23317. ><TT
  23318. CLASS="constant"
  23319. ><B
  23320. >TRUE</B
  23321. ></TT
  23322. > if either $a or $b is <TT
  23323. CLASS="constant"
  23324. ><B
  23325. >TRUE</B
  23326. ></TT
  23327. >.</TD
  23328. ></TR
  23329. ><TR
  23330. ><TD
  23331. >$a xor $b</TD
  23332. ><TD
  23333. >Xor</TD
  23334. ><TD
  23335. ><TT
  23336. CLASS="constant"
  23337. ><B
  23338. >TRUE</B
  23339. ></TT
  23340. > if either $a or $b is <TT
  23341. CLASS="constant"
  23342. ><B
  23343. >TRUE</B
  23344. ></TT
  23345. >, but not both.</TD
  23346. ></TR
  23347. ><TR
  23348. ><TD
  23349. >! $a</TD
  23350. ><TD
  23351. >Not</TD
  23352. ><TD
  23353. ><TT
  23354. CLASS="constant"
  23355. ><B
  23356. >TRUE</B
  23357. ></TT
  23358. > if $a is not <TT
  23359. CLASS="constant"
  23360. ><B
  23361. >TRUE</B
  23362. ></TT
  23363. >.</TD
  23364. ></TR
  23365. ><TR
  23366. ><TD
  23367. >$a && $b</TD
  23368. ><TD
  23369. >And</TD
  23370. ><TD
  23371. ><TT
  23372. CLASS="constant"
  23373. ><B
  23374. >TRUE</B
  23375. ></TT
  23376. > if both $a and $b are <TT
  23377. CLASS="constant"
  23378. ><B
  23379. >TRUE</B
  23380. ></TT
  23381. >.</TD
  23382. ></TR
  23383. ><TR
  23384. ><TD
  23385. >$a || $b</TD
  23386. ><TD
  23387. >Or</TD
  23388. ><TD
  23389. ><TT
  23390. CLASS="constant"
  23391. ><B
  23392. >TRUE</B
  23393. ></TT
  23394. > if either $a or $b is <TT
  23395. CLASS="constant"
  23396. ><B
  23397. >TRUE</B
  23398. ></TT
  23399. >.</TD
  23400. ></TR
  23401. ></TBODY
  23402. ></TABLE
  23403. ></DIV
  23404. ><P
  23405. >     The reason for the two different variations of "and" and "or"
  23406.     operators is that they operate at different precedences. (See
  23407.     <A
  23408. HREF="#language.operators.precedence"
  23409. >Operator
  23410.     Precedence</A
  23411. >.)
  23412.    </P
  23413. ></DIV
  23414. ><DIV
  23415. CLASS="sect1"
  23416. ><HR><H2
  23417. CLASS="sect1"
  23418. ><A
  23419. NAME="language.operators.string"
  23420. >String Operators</A
  23421. ></H2
  23422. ><P
  23423. >     There are two <A
  23424. HREF="#language.types.string"
  23425. ><B
  23426. CLASS="type"
  23427. >string</B
  23428. ></A
  23429. > operators. The first is the
  23430.     concatenation operator ('.'), which returns the concatenation of its
  23431.     right and left arguments. The second is the concatenating assignment
  23432.     operator ('.='), which appends the argument on the right side to
  23433.     the argument on the left side. Please read <A
  23434. HREF="#language.operators.assignment"
  23435. >Assignment
  23436.     Operators</A
  23437. > for more information.
  23438.    </P
  23439. ><P
  23440. >     <DIV
  23441. CLASS="informalexample"
  23442. ><P
  23443. ></P
  23444. ><A
  23445. NAME="AEN4270"
  23446. ></A
  23447. ><TABLE
  23448. BORDER="0"
  23449. BGCOLOR="#E0E0E0"
  23450. CELLPADDING="5"
  23451. ><TR
  23452. ><TD
  23453. ><PRE
  23454. CLASS="php"
  23455. ><?php
  23456. $a = "Hello ";
  23457. $b = $a . "World!"; // now $b contains "Hello World!"
  23458.  
  23459. $a = "Hello ";
  23460. $a .= "World!";     // now $a contains "Hello World!"
  23461. ?></PRE
  23462. ></TD
  23463. ></TR
  23464. ></TABLE
  23465. ><P
  23466. ></P
  23467. ></DIV
  23468. >
  23469.    </P
  23470. ><P
  23471. >     See also the manual sections on the 
  23472.     <A
  23473. HREF="#language.types.string"
  23474. >String type</A
  23475. > and 
  23476.     <A
  23477. HREF="#ref.strings"
  23478. >String functions</A
  23479. >.
  23480.    </P
  23481. ></DIV
  23482. ><DIV
  23483. CLASS="sect1"
  23484. ><HR><H2
  23485. CLASS="sect1"
  23486. ><A
  23487. NAME="language.operators.array"
  23488. >Array Operators</A
  23489. ></H2
  23490. ><DIV
  23491. CLASS="table"
  23492. ><A
  23493. NAME="AEN4277"
  23494. ></A
  23495. ><P
  23496. ><B
  23497. >Table 15-7. Array Operators</B
  23498. ></P
  23499. ><TABLE
  23500. BORDER="1"
  23501. CLASS="CALSTABLE"
  23502. ><COL><COL><COL><THEAD
  23503. ><TR
  23504. ><TH
  23505. >Example</TH
  23506. ><TH
  23507. >Name</TH
  23508. ><TH
  23509. >Result</TH
  23510. ></TR
  23511. ></THEAD
  23512. ><TBODY
  23513. ><TR
  23514. ><TD
  23515. >$a + $b</TD
  23516. ><TD
  23517. >Union</TD
  23518. ><TD
  23519. >Union of $a and $b.</TD
  23520. ></TR
  23521. ><TR
  23522. ><TD
  23523. >$a == $b</TD
  23524. ><TD
  23525. >Equality</TD
  23526. ><TD
  23527. ><TT
  23528. CLASS="constant"
  23529. ><B
  23530. >TRUE</B
  23531. ></TT
  23532. > if $a and $b have the same key/value pairs.</TD
  23533. ></TR
  23534. ><TR
  23535. ><TD
  23536. >$a === $b</TD
  23537. ><TD
  23538. >Identity</TD
  23539. ><TD
  23540. ><TT
  23541. CLASS="constant"
  23542. ><B
  23543. >TRUE</B
  23544. ></TT
  23545. > if $a and $b have the same key/value pairs in the same
  23546.         order and of the same types.</TD
  23547. ></TR
  23548. ><TR
  23549. ><TD
  23550. >$a != $b</TD
  23551. ><TD
  23552. >Inequality</TD
  23553. ><TD
  23554. ><TT
  23555. CLASS="constant"
  23556. ><B
  23557. >TRUE</B
  23558. ></TT
  23559. > if $a is not equal to $b.</TD
  23560. ></TR
  23561. ><TR
  23562. ><TD
  23563. >$a <> $b</TD
  23564. ><TD
  23565. >Inequality</TD
  23566. ><TD
  23567. ><TT
  23568. CLASS="constant"
  23569. ><B
  23570. >TRUE</B
  23571. ></TT
  23572. > if $a is not equal to $b.</TD
  23573. ></TR
  23574. ><TR
  23575. ><TD
  23576. >$a !== $b</TD
  23577. ><TD
  23578. >Non-identity</TD
  23579. ><TD
  23580. ><TT
  23581. CLASS="constant"
  23582. ><B
  23583. >TRUE</B
  23584. ></TT
  23585. > if $a is not identical to $b.</TD
  23586. ></TR
  23587. ></TBODY
  23588. ></TABLE
  23589. ></DIV
  23590. ><P
  23591. >     The <VAR
  23592. CLASS="literal"
  23593. >+</VAR
  23594. > operator
  23595.     appends the right handed array to the left handed, whereas 
  23596.     duplicated keys are NOT overwritten.
  23597.    </P
  23598. ><P
  23599. >     <DIV
  23600. CLASS="informalexample"
  23601. ><P
  23602. ></P
  23603. ><A
  23604. NAME="AEN4318"
  23605. ></A
  23606. ><TABLE
  23607. BORDER="0"
  23608. BGCOLOR="#E0E0E0"
  23609. CELLPADDING="5"
  23610. ><TR
  23611. ><TD
  23612. ><PRE
  23613. CLASS="php"
  23614. ><?php
  23615. $a = array("a" => "apple", "b" => "banana");
  23616. $b = array("a" => "pear", "b" => "strawberry", "c" => "cherry");
  23617.  
  23618. $c = $a + $b; // Union of $a and $b
  23619. echo "Union of \$a and \$b: \n";
  23620. var_dump($c);
  23621.  
  23622. $c = $b + $a; // Union of $b and $a
  23623. echo "Union of \$b and \$a: \n";
  23624. var_dump($c);
  23625. ?></PRE
  23626. ></TD
  23627. ></TR
  23628. ></TABLE
  23629. ><P
  23630. ></P
  23631. ></DIV
  23632. >
  23633.     When executed, this script will print the following:
  23634.     <TABLE
  23635. BORDER="0"
  23636. BGCOLOR="#E0E0E0"
  23637. CELLPADDING="5"
  23638. ><TR
  23639. ><TD
  23640. ><PRE
  23641. CLASS="php"
  23642. >Union of $a and $b:
  23643. array(3) {
  23644.   ["a"]=>
  23645.   string(5) "apple"
  23646.   ["b"]=>
  23647.   string(6) "banana"
  23648.   ["c"]=>
  23649.   string(6) "cherry"
  23650. }
  23651. Union of $b and $a:
  23652. array(3) {
  23653.   ["a"]=>
  23654.   string(4) "pear"
  23655.   ["b"]=>
  23656.   string(10) "strawberry"
  23657.   ["c"]=>
  23658.   string(6) "cherry"
  23659. }</PRE
  23660. ></TD
  23661. ></TR
  23662. ></TABLE
  23663. >
  23664.    </P
  23665. ><P
  23666. >     Elements of arrays are equal for the comparison if they have the
  23667.     same key and value.
  23668.    </P
  23669. ><P
  23670. >     <TABLE
  23671. WIDTH="100%"
  23672. BORDER="0"
  23673. CELLPADDING="0"
  23674. CELLSPACING="0"
  23675. CLASS="EXAMPLE"
  23676. ><TR
  23677. ><TD
  23678. ><DIV
  23679. CLASS="example"
  23680. ><A
  23681. NAME="AEN4323"
  23682. ></A
  23683. ><P
  23684. ><B
  23685. >Example 15-3. Comparing arrays</B
  23686. ></P
  23687. ><TABLE
  23688. BORDER="0"
  23689. BGCOLOR="#E0E0E0"
  23690. CELLPADDING="5"
  23691. ><TR
  23692. ><TD
  23693. ><PRE
  23694. CLASS="php"
  23695. ><?php
  23696. $a = array("apple", "banana");
  23697. $b = array(1 => "banana", "0" => "apple");
  23698.  
  23699. var_dump($a == $b); // bool(true)
  23700. var_dump($a === $b); // bool(false)
  23701. ?></PRE
  23702. ></TD
  23703. ></TR
  23704. ></TABLE
  23705. ></DIV
  23706. ></TD
  23707. ></TR
  23708. ></TABLE
  23709. >
  23710.    </P
  23711. ><P
  23712. >     See also the manual sections on the 
  23713.     <A
  23714. HREF="#language.types.array"
  23715. >Array type</A
  23716. > and 
  23717.     <A
  23718. HREF="#ref.array"
  23719. >Array functions</A
  23720. >.
  23721.    </P
  23722. ></DIV
  23723. ><DIV
  23724. CLASS="sect1"
  23725. ><HR><H2
  23726. CLASS="sect1"
  23727. ><A
  23728. NAME="language.operators.type"
  23729. >Type Operators</A
  23730. ></H2
  23731. ><P
  23732. >     PHP has a single type operator: <VAR
  23733. CLASS="literal"
  23734. >instanceof</VAR
  23735. >. 
  23736.     <VAR
  23737. CLASS="literal"
  23738. >instanceof</VAR
  23739. > is used to determine whether a given
  23740.     object is of a specified <A
  23741. HREF="#language.oop"
  23742. >object class</A
  23743. >.
  23744.    </P
  23745. ><P
  23746. >     The <VAR
  23747. CLASS="literal"
  23748. >instanceof</VAR
  23749. > operator was introduced in PHP 5.
  23750.     Before this time <A
  23751. HREF="#function.is-a"
  23752. ><B
  23753. CLASS="function"
  23754. >is_a()</B
  23755. ></A
  23756. > was used but
  23757.     <A
  23758. HREF="#function.is-a"
  23759. ><B
  23760. CLASS="function"
  23761. >is_a()</B
  23762. ></A
  23763. > has since been deprecated in favor of
  23764.     <VAR
  23765. CLASS="literal"
  23766. >instanceof</VAR
  23767. >. 
  23768.    </P
  23769. ><DIV
  23770. CLASS="informalexample"
  23771. ><P
  23772. ></P
  23773. ><A
  23774. NAME="AEN4340"
  23775. ></A
  23776. ><TABLE
  23777. BORDER="0"
  23778. BGCOLOR="#E0E0E0"
  23779. CELLPADDING="5"
  23780. ><TR
  23781. ><TD
  23782. ><PRE
  23783. CLASS="programlisting"
  23784. ><?php
  23785. class A { }
  23786. class B { }
  23787.  
  23788. $thing = new A;
  23789.  
  23790. if ($thing instanceof A) {
  23791.     echo 'A';
  23792. }
  23793. if ($thing instanceof B) {
  23794.     echo 'B';
  23795. }
  23796. ?></PRE
  23797. ></TD
  23798. ></TR
  23799. ></TABLE
  23800. ><P
  23801. >      As <VAR
  23802. CLASS="varname"
  23803. >$thing</VAR
  23804. > is an <A
  23805. HREF="#language.types.object"
  23806. ><B
  23807. CLASS="type"
  23808. >object</B
  23809. ></A
  23810. > of type A, but
  23811.      not B, only the block dependent on the A type will be executed:
  23812.     </P
  23813. ><TABLE
  23814. BORDER="0"
  23815. BGCOLOR="#E0E0E0"
  23816. CELLPADDING="5"
  23817. ><TR
  23818. ><TD
  23819. ><PRE
  23820. CLASS="screen"
  23821. >A</PRE
  23822. ></TD
  23823. ></TR
  23824. ></TABLE
  23825. ><P
  23826. ></P
  23827. ></DIV
  23828. ><P
  23829. >     See also <A
  23830. HREF="#function.get-class"
  23831. ><B
  23832. CLASS="function"
  23833. >get_class()</B
  23834. ></A
  23835. > and 
  23836.     <A
  23837. HREF="#function.is-a"
  23838. ><B
  23839. CLASS="function"
  23840. >is_a()</B
  23841. ></A
  23842. >.
  23843.    </P
  23844. ></DIV
  23845. ></DIV
  23846. ><DIV
  23847. CLASS="chapter"
  23848. ><HR><H1
  23849. ><A
  23850. NAME="language.control-structures"
  23851. >Chapter 16. Control Structures</A
  23852. ></H1
  23853. ><P
  23854. >    Any PHP script is built out of a series of statements. A statement
  23855.    can be an assignment, a function call, a loop, a conditional
  23856.    statement of even a statement that does nothing (an empty
  23857.    statement). Statements usually end with a semicolon. In addition,
  23858.    statements can be grouped into a statement-group by encapsulating a
  23859.    group of statements with curly braces. A statement-group is a
  23860.    statement by itself as well. The various statement types are
  23861.    described in this chapter.
  23862.   </P
  23863. ><DIV
  23864. CLASS="sect1"
  23865. ><HR><H2
  23866. CLASS="sect1"
  23867. ><A
  23868. NAME="control-structures.if"
  23869. ><VAR
  23870. CLASS="literal"
  23871. >if</VAR
  23872. ></A
  23873. ></H2
  23874. ><P
  23875. >     The <VAR
  23876. CLASS="literal"
  23877. >if</VAR
  23878. > construct is one of the most important
  23879.     features of many languages, PHP included.  It allows for
  23880.     conditional execution of code fragments.  PHP features an
  23881.     <VAR
  23882. CLASS="literal"
  23883. >if</VAR
  23884. > structure that is similar to that of C:
  23885.     <DIV
  23886. CLASS="informalexample"
  23887. ><P
  23888. ></P
  23889. ><A
  23890. NAME="AEN4358"
  23891. ></A
  23892. ><TABLE
  23893. BORDER="0"
  23894. BGCOLOR="#E0E0E0"
  23895. CELLPADDING="5"
  23896. ><TR
  23897. ><TD
  23898. ><PRE
  23899. CLASS="programlisting"
  23900. ><?php
  23901. if (expression)
  23902.     statement
  23903. ?></PRE
  23904. ></TD
  23905. ></TR
  23906. ></TABLE
  23907. ><P
  23908. ></P
  23909. ></DIV
  23910. >
  23911.    </P
  23912. ><P
  23913. >     As described in <A
  23914. HREF="#language.expressions"
  23915. >the section about
  23916.     expressions</A
  23917. >, <VAR
  23918. CLASS="replaceable"
  23919. >expr</VAR
  23920. > is evaluated to its
  23921.     Boolean value.  If <VAR
  23922. CLASS="replaceable"
  23923. >expr</VAR
  23924. > evaluates to <TT
  23925. CLASS="constant"
  23926. ><B
  23927. >TRUE</B
  23928. ></TT
  23929. >,
  23930.    PHP will execute <VAR
  23931. CLASS="replaceable"
  23932. >statement</VAR
  23933. >, and if it evaluates
  23934.     to <TT
  23935. CLASS="constant"
  23936. ><B
  23937. >FALSE</B
  23938. ></TT
  23939. > - it'll ignore it. More information about what values evaluate
  23940.     to <TT
  23941. CLASS="constant"
  23942. ><B
  23943. >FALSE</B
  23944. ></TT
  23945. > can be found in the <A
  23946. HREF="#language.types.boolean.casting"
  23947. >'Converting to boolean'</A
  23948. >
  23949.     section.
  23950.    </P
  23951. ><P
  23952. >     The following example would display <SAMP
  23953. CLASS="computeroutput"
  23954. >a is bigger
  23955.     than b</SAMP
  23956. > if <VAR
  23957. CLASS="varname"
  23958. >$a</VAR
  23959. > is bigger
  23960.     than <VAR
  23961. CLASS="varname"
  23962. >$b</VAR
  23963. >:
  23964.     <DIV
  23965. CLASS="informalexample"
  23966. ><P
  23967. ></P
  23968. ><A
  23969. NAME="AEN4373"
  23970. ></A
  23971. ><TABLE
  23972. BORDER="0"
  23973. BGCOLOR="#E0E0E0"
  23974. CELLPADDING="5"
  23975. ><TR
  23976. ><TD
  23977. ><PRE
  23978. CLASS="php"
  23979. ><?php
  23980. if ($a > $b)
  23981.     echo "a is bigger than b";
  23982. ?></PRE
  23983. ></TD
  23984. ></TR
  23985. ></TABLE
  23986. ><P
  23987. ></P
  23988. ></DIV
  23989. >
  23990.    </P
  23991. ><P
  23992. >     Often you'd want to have more than one statement to be executed
  23993.     conditionally.  Of course, there's no need to wrap each statement
  23994.     with an <VAR
  23995. CLASS="literal"
  23996. >if</VAR
  23997. > clause.  Instead, you can group
  23998.     several statements into a statement group.  For example, this code
  23999.     would display <SAMP
  24000. CLASS="computeroutput"
  24001. >a is bigger than b</SAMP
  24002. >
  24003.     if <VAR
  24004. CLASS="varname"
  24005. >$a</VAR
  24006. > is bigger than
  24007.     <VAR
  24008. CLASS="varname"
  24009. >$b</VAR
  24010. >, and would then assign the value of
  24011.     <VAR
  24012. CLASS="varname"
  24013. >$a</VAR
  24014. > into <VAR
  24015. CLASS="varname"
  24016. >$b</VAR
  24017. >:
  24018.     <DIV
  24019. CLASS="informalexample"
  24020. ><P
  24021. ></P
  24022. ><A
  24023. NAME="AEN4382"
  24024. ></A
  24025. ><TABLE
  24026. BORDER="0"
  24027. BGCOLOR="#E0E0E0"
  24028. CELLPADDING="5"
  24029. ><TR
  24030. ><TD
  24031. ><PRE
  24032. CLASS="php"
  24033. ><?php
  24034. if ($a > $b) {
  24035.     echo "a is bigger than b";
  24036.     $b = $a;
  24037. }
  24038. ?></PRE
  24039. ></TD
  24040. ></TR
  24041. ></TABLE
  24042. ><P
  24043. ></P
  24044. ></DIV
  24045. >
  24046.    </P
  24047. ><P
  24048. >     <VAR
  24049. CLASS="literal"
  24050. >If</VAR
  24051. > statements can be nested indefinitely within other
  24052.     <VAR
  24053. CLASS="literal"
  24054. >if</VAR
  24055. > statements, which provides you with complete
  24056.     flexibility for conditional execution of the various parts of your
  24057.     program.
  24058.    </P
  24059. ></DIV
  24060. ><DIV
  24061. CLASS="sect1"
  24062. ><HR><H2
  24063. CLASS="sect1"
  24064. ><A
  24065. NAME="control-structures.else"
  24066. ><VAR
  24067. CLASS="literal"
  24068. >else</VAR
  24069. ></A
  24070. ></H2
  24071. ><P
  24072. >     Often you'd want to execute a statement if a certain condition is
  24073.     met, and a different statement if the condition is not met.  This
  24074.     is what <VAR
  24075. CLASS="literal"
  24076. >else</VAR
  24077. > is for.  <VAR
  24078. CLASS="literal"
  24079. >else</VAR
  24080. >
  24081.     extends an <VAR
  24082. CLASS="literal"
  24083. >if</VAR
  24084. > statement to execute a statement
  24085.     in case the expression in the <VAR
  24086. CLASS="literal"
  24087. >if</VAR
  24088. > statement
  24089.     evaluates to <TT
  24090. CLASS="constant"
  24091. ><B
  24092. >FALSE</B
  24093. ></TT
  24094. >.  For example, the following
  24095.     code would display <SAMP
  24096. CLASS="computeroutput"
  24097. >a is bigger than
  24098.     b</SAMP
  24099. > if <VAR
  24100. CLASS="varname"
  24101. >$a</VAR
  24102. > is bigger than
  24103.     <VAR
  24104. CLASS="varname"
  24105. >$b</VAR
  24106. >, and <SAMP
  24107. CLASS="computeroutput"
  24108. >a is NOT bigger
  24109.     than b</SAMP
  24110. > otherwise:
  24111.     <DIV
  24112. CLASS="informalexample"
  24113. ><P
  24114. ></P
  24115. ><A
  24116. NAME="AEN4400"
  24117. ></A
  24118. ><TABLE
  24119. BORDER="0"
  24120. BGCOLOR="#E0E0E0"
  24121. CELLPADDING="5"
  24122. ><TR
  24123. ><TD
  24124. ><PRE
  24125. CLASS="php"
  24126. ><?php
  24127. if ($a > $b) {
  24128.     echo "a is bigger than b";
  24129. } else {
  24130.     echo "a is NOT bigger than b";
  24131. }
  24132. ?></PRE
  24133. ></TD
  24134. ></TR
  24135. ></TABLE
  24136. ><P
  24137. ></P
  24138. ></DIV
  24139. >
  24140.  
  24141.     The <VAR
  24142. CLASS="literal"
  24143. >else</VAR
  24144. > statement is only executed if the
  24145.     <VAR
  24146. CLASS="literal"
  24147. >if</VAR
  24148. > expression evaluated to
  24149.     <TT
  24150. CLASS="constant"
  24151. ><B
  24152. >FALSE</B
  24153. ></TT
  24154. >, and if there were any
  24155.     <VAR
  24156. CLASS="literal"
  24157. >elseif</VAR
  24158. > expressions - only if they evaluated to
  24159.     <TT
  24160. CLASS="constant"
  24161. ><B
  24162. >FALSE</B
  24163. ></TT
  24164. > as well (see <A
  24165. HREF="#control-structures.elseif"
  24166. >elseif</A
  24167. >).
  24168.  
  24169.    </P
  24170. ></DIV
  24171. ><DIV
  24172. CLASS="sect1"
  24173. ><HR><H2
  24174. CLASS="sect1"
  24175. ><A
  24176. NAME="control-structures.elseif"
  24177. ><VAR
  24178. CLASS="literal"
  24179. >elseif</VAR
  24180. ></A
  24181. ></H2
  24182. ><P
  24183. >     <VAR
  24184. CLASS="literal"
  24185. >elseif</VAR
  24186. >, as its name suggests, is a combination
  24187.     of <VAR
  24188. CLASS="literal"
  24189. >if</VAR
  24190. > and <VAR
  24191. CLASS="literal"
  24192. >else</VAR
  24193. >.  Like
  24194.     <VAR
  24195. CLASS="literal"
  24196. >else</VAR
  24197. >, it extends an <VAR
  24198. CLASS="literal"
  24199. >if</VAR
  24200. >
  24201.     statement to execute a different statement in case the original
  24202.     <VAR
  24203. CLASS="literal"
  24204. >if</VAR
  24205. > expression evaluates to
  24206.     <TT
  24207. CLASS="constant"
  24208. ><B
  24209. >FALSE</B
  24210. ></TT
  24211. >.  However, unlike
  24212.     <VAR
  24213. CLASS="literal"
  24214. >else</VAR
  24215. >, it will execute that alternative
  24216.     expression only if the <VAR
  24217. CLASS="literal"
  24218. >elseif</VAR
  24219. > conditional
  24220.     expression evaluates to <TT
  24221. CLASS="constant"
  24222. ><B
  24223. >TRUE</B
  24224. ></TT
  24225. >.  For example, the
  24226.     following code would display <SAMP
  24227. CLASS="computeroutput"
  24228. >a is bigger than
  24229.     b</SAMP
  24230. >, <SAMP
  24231. CLASS="computeroutput"
  24232. >a equal to b</SAMP
  24233. >
  24234.     or <SAMP
  24235. CLASS="computeroutput"
  24236. >a is smaller than b</SAMP
  24237. >:
  24238.     <DIV
  24239. CLASS="informalexample"
  24240. ><P
  24241. ></P
  24242. ><A
  24243. NAME="AEN4425"
  24244. ></A
  24245. ><TABLE
  24246. BORDER="0"
  24247. BGCOLOR="#E0E0E0"
  24248. CELLPADDING="5"
  24249. ><TR
  24250. ><TD
  24251. ><PRE
  24252. CLASS="php"
  24253. ><?php
  24254. if ($a > $b) {
  24255.     echo "a is bigger than b";
  24256. } elseif ($a == $b) {
  24257.     echo "a is equal to b";
  24258. } else {
  24259.     echo "a is smaller than b";
  24260. }
  24261. ?></PRE
  24262. ></TD
  24263. ></TR
  24264. ></TABLE
  24265. ><P
  24266. ></P
  24267. ></DIV
  24268. >
  24269.    </P
  24270. ><P
  24271. >     There may be several <VAR
  24272. CLASS="literal"
  24273. >elseif</VAR
  24274. >s within the same
  24275.     <VAR
  24276. CLASS="literal"
  24277. >if</VAR
  24278. > statement.  The first
  24279.     <VAR
  24280. CLASS="literal"
  24281. >elseif</VAR
  24282. > expression (if any) that evaluates to
  24283.     <TT
  24284. CLASS="constant"
  24285. ><B
  24286. >TRUE</B
  24287. ></TT
  24288. > would be executed.  In PHP, you can also
  24289.     write 'else if' (in two words) and the behavior would be identical
  24290.     to the one of 'elseif' (in a single word).  The syntactic meaning
  24291.     is slightly different (if you're familiar with C, this is the same
  24292.     behavior) but the bottom line is that both would result in exactly
  24293.     the same behavior.
  24294.    </P
  24295. ><P
  24296. >     The <VAR
  24297. CLASS="literal"
  24298. >elseif</VAR
  24299. > statement is only executed if the
  24300.     preceding <VAR
  24301. CLASS="literal"
  24302. >if</VAR
  24303. > expression and any preceding
  24304.     <VAR
  24305. CLASS="literal"
  24306. >elseif</VAR
  24307. > expressions evaluated to
  24308.     <TT
  24309. CLASS="constant"
  24310. ><B
  24311. >FALSE</B
  24312. ></TT
  24313. >, and the current
  24314.     <VAR
  24315. CLASS="literal"
  24316. >elseif</VAR
  24317. > expression evaluated to
  24318.     <TT
  24319. CLASS="constant"
  24320. ><B
  24321. >TRUE</B
  24322. ></TT
  24323. >.
  24324.    </P
  24325. ></DIV
  24326. ><DIV
  24327. CLASS="sect1"
  24328. ><HR><H2
  24329. CLASS="sect1"
  24330. ><A
  24331. NAME="control-structures.alternative-syntax"
  24332. >Alternative syntax for control structures</A
  24333. ></H2
  24334. ><P
  24335. >     PHP offers an alternative syntax for some of its control
  24336.     structures; namely, <VAR
  24337. CLASS="literal"
  24338. >if</VAR
  24339. >,
  24340.     <VAR
  24341. CLASS="literal"
  24342. >while</VAR
  24343. >, <VAR
  24344. CLASS="literal"
  24345. >for</VAR
  24346. >,
  24347.     <VAR
  24348. CLASS="literal"
  24349. >foreach</VAR
  24350. >, and <VAR
  24351. CLASS="literal"
  24352. >switch</VAR
  24353. >.
  24354.     In each case, the basic form of the alternate syntax is to change
  24355.     the opening brace to a colon (:) and the closing brace to
  24356.     <VAR
  24357. CLASS="literal"
  24358. >endif;</VAR
  24359. >, <VAR
  24360. CLASS="literal"
  24361. >endwhile;</VAR
  24362. >,
  24363.     <VAR
  24364. CLASS="literal"
  24365. >endfor;</VAR
  24366. >, <VAR
  24367. CLASS="literal"
  24368. >endforeach;</VAR
  24369. >, or
  24370.     <VAR
  24371. CLASS="literal"
  24372. >endswitch;</VAR
  24373. >, respectively.
  24374.     <DIV
  24375. CLASS="informalexample"
  24376. ><P
  24377. ></P
  24378. ><A
  24379. NAME="AEN4452"
  24380. ></A
  24381. ><TABLE
  24382. BORDER="0"
  24383. BGCOLOR="#E0E0E0"
  24384. CELLPADDING="5"
  24385. ><TR
  24386. ><TD
  24387. ><PRE
  24388. CLASS="php"
  24389. ><?php if ($a == 5): ?>
  24390. A is equal to 5
  24391. <?php endif; ?></PRE
  24392. ></TD
  24393. ></TR
  24394. ></TABLE
  24395. ><P
  24396. ></P
  24397. ></DIV
  24398. >
  24399.    </P
  24400. ><P
  24401. >     In the above example, the HTML block "A is equal to 5" is nested within an
  24402.     <VAR
  24403. CLASS="literal"
  24404. >if</VAR
  24405. > statement written in the alternative syntax.  The
  24406.     HTML block would be displayed only if <VAR
  24407. CLASS="varname"
  24408. >$a</VAR
  24409. > is equal to 5.
  24410.    </P
  24411. ><P
  24412. >     The alternative syntax applies to <VAR
  24413. CLASS="literal"
  24414. >else</VAR
  24415. > and
  24416.     <VAR
  24417. CLASS="literal"
  24418. >elseif</VAR
  24419. > as well.  The following is an
  24420.     <VAR
  24421. CLASS="literal"
  24422. >if</VAR
  24423. > structure with <VAR
  24424. CLASS="literal"
  24425. >elseif</VAR
  24426. > and
  24427.     <VAR
  24428. CLASS="literal"
  24429. >else</VAR
  24430. > in the alternative format:
  24431.     <DIV
  24432. CLASS="informalexample"
  24433. ><P
  24434. ></P
  24435. ><A
  24436. NAME="AEN4463"
  24437. ></A
  24438. ><TABLE
  24439. BORDER="0"
  24440. BGCOLOR="#E0E0E0"
  24441. CELLPADDING="5"
  24442. ><TR
  24443. ><TD
  24444. ><PRE
  24445. CLASS="php"
  24446. ><?php
  24447. if ($a == 5):
  24448.     echo "a equals 5";
  24449.     echo "...";
  24450. elseif ($a == 6):
  24451.     echo "a equals 6";
  24452.     echo "!!!";
  24453. else:
  24454.     echo "a is neither 5 nor 6";
  24455. endif;
  24456. ?></PRE
  24457. ></TD
  24458. ></TR
  24459. ></TABLE
  24460. ><P
  24461. ></P
  24462. ></DIV
  24463. >
  24464.    </P
  24465. ><P
  24466. >     See also <A
  24467. HREF="#control-structures.while"
  24468. >while</A
  24469. >,
  24470.     <A
  24471. HREF="#control-structures.for"
  24472. >for</A
  24473. >, and <A
  24474. HREF="#control-structures.if"
  24475. >if</A
  24476. > for further examples.
  24477.    </P
  24478. ></DIV
  24479. ><DIV
  24480. CLASS="sect1"
  24481. ><HR><H2
  24482. CLASS="sect1"
  24483. ><A
  24484. NAME="control-structures.while"
  24485. ><VAR
  24486. CLASS="literal"
  24487. >while</VAR
  24488. ></A
  24489. ></H2
  24490. ><P
  24491. >     <VAR
  24492. CLASS="literal"
  24493. >while</VAR
  24494. > loops are the simplest type of loop in
  24495.     PHP.  They behave just like their C counterparts.  The basic form
  24496.     of a <VAR
  24497. CLASS="literal"
  24498. >while</VAR
  24499. > statement is:
  24500.     <DIV
  24501. CLASS="informalexample"
  24502. ><P
  24503. ></P
  24504. ><A
  24505. NAME="AEN4475"
  24506. ></A
  24507. ><TABLE
  24508. BORDER="0"
  24509. BGCOLOR="#E0E0E0"
  24510. CELLPADDING="5"
  24511. ><TR
  24512. ><TD
  24513. ><PRE
  24514. CLASS="programlisting"
  24515. >while (expr)
  24516.     statement</PRE
  24517. ></TD
  24518. ></TR
  24519. ></TABLE
  24520. ><P
  24521. ></P
  24522. ></DIV
  24523. >
  24524.    </P
  24525. ><P
  24526. >     The meaning of a <VAR
  24527. CLASS="literal"
  24528. >while</VAR
  24529. > statement is simple.  It
  24530.     tells PHP to execute the nested statement(s) repeatedly, as long
  24531.     as the <VAR
  24532. CLASS="literal"
  24533. >while</VAR
  24534. > expression evaluates to
  24535.     <TT
  24536. CLASS="constant"
  24537. ><B
  24538. >TRUE</B
  24539. ></TT
  24540. >.  The value of the expression is checked
  24541.     each time at the beginning of the loop, so even if this value
  24542.     changes during the execution of the nested statement(s), execution
  24543.     will not stop until the end of the iteration (each time PHP runs
  24544.     the statements in the loop is one iteration).  Sometimes, if the
  24545.     <VAR
  24546. CLASS="literal"
  24547. >while</VAR
  24548. > expression evaluates to
  24549.     <TT
  24550. CLASS="constant"
  24551. ><B
  24552. >FALSE</B
  24553. ></TT
  24554. > from the very beginning, the nested
  24555.     statement(s) won't even be run once.
  24556.    </P
  24557. ><P
  24558. >     Like with the <VAR
  24559. CLASS="literal"
  24560. >if</VAR
  24561. > statement, you can group
  24562.     multiple statements within the same <VAR
  24563. CLASS="literal"
  24564. >while</VAR
  24565. > loop
  24566.     by surrounding a group of statements with curly braces, or by
  24567.     using the alternate syntax:
  24568.     <DIV
  24569. CLASS="informalexample"
  24570. ><P
  24571. ></P
  24572. ><A
  24573. NAME="AEN4486"
  24574. ></A
  24575. ><TABLE
  24576. BORDER="0"
  24577. BGCOLOR="#E0E0E0"
  24578. CELLPADDING="5"
  24579. ><TR
  24580. ><TD
  24581. ><PRE
  24582. CLASS="programlisting"
  24583. >while (expr):
  24584.     statement
  24585.     ...
  24586. endwhile;</PRE
  24587. ></TD
  24588. ></TR
  24589. ></TABLE
  24590. ><P
  24591. ></P
  24592. ></DIV
  24593. >
  24594.    </P
  24595. ><P
  24596. >     The following examples are identical, and both print numbers from
  24597.     1 to 10:
  24598.     <DIV
  24599. CLASS="informalexample"
  24600. ><P
  24601. ></P
  24602. ><A
  24603. NAME="AEN4489"
  24604. ></A
  24605. ><TABLE
  24606. BORDER="0"
  24607. BGCOLOR="#E0E0E0"
  24608. CELLPADDING="5"
  24609. ><TR
  24610. ><TD
  24611. ><PRE
  24612. CLASS="php"
  24613. ><?php
  24614. /* example 1 */
  24615.  
  24616. $i = 1;
  24617. while ($i <= 10) {
  24618.     echo $i++;  /* the printed value would be
  24619.                     $i before the increment
  24620.                     (post-increment) */
  24621. }
  24622.  
  24623. /* example 2 */
  24624.  
  24625. $i = 1;
  24626. while ($i <= 10):
  24627.     echo $i;
  24628.     $i++;
  24629. endwhile;
  24630. ?></PRE
  24631. ></TD
  24632. ></TR
  24633. ></TABLE
  24634. ><P
  24635. ></P
  24636. ></DIV
  24637. >
  24638.    </P
  24639. ></DIV
  24640. ><DIV
  24641. CLASS="sect1"
  24642. ><HR><H2
  24643. CLASS="sect1"
  24644. ><A
  24645. NAME="control-structures.do.while"
  24646. ><VAR
  24647. CLASS="literal"
  24648. >do-while</VAR
  24649. ></A
  24650. ></H2
  24651. ><P
  24652. >     <VAR
  24653. CLASS="literal"
  24654. >do-while</VAR
  24655. > loops are very similar to
  24656.     <VAR
  24657. CLASS="literal"
  24658. >while</VAR
  24659. > loops, except the truth expression is
  24660.     checked at the end of each iteration instead of in the beginning.
  24661.     The main difference from regular <VAR
  24662. CLASS="literal"
  24663. >while</VAR
  24664. > loops is
  24665.     that the first iteration of a <VAR
  24666. CLASS="literal"
  24667. >do-while</VAR
  24668. > loop is
  24669.     guaranteed to run (the truth expression is only checked at the end
  24670.     of the iteration), whereas it's may not necessarily run with a
  24671.     regular <VAR
  24672. CLASS="literal"
  24673. >while</VAR
  24674. > loop (the truth expression is
  24675.     checked at the beginning of each iteration, if it evaluates to
  24676.     <TT
  24677. CLASS="constant"
  24678. ><B
  24679. >FALSE</B
  24680. ></TT
  24681. > right from the beginning, the loop
  24682.     execution would end immediately).
  24683.    </P
  24684. ><P
  24685. >     There is just one syntax for <VAR
  24686. CLASS="literal"
  24687. >do-while</VAR
  24688. > loops:
  24689.  
  24690.     <DIV
  24691. CLASS="informalexample"
  24692. ><P
  24693. ></P
  24694. ><A
  24695. NAME="AEN4503"
  24696. ></A
  24697. ><TABLE
  24698. BORDER="0"
  24699. BGCOLOR="#E0E0E0"
  24700. CELLPADDING="5"
  24701. ><TR
  24702. ><TD
  24703. ><PRE
  24704. CLASS="php"
  24705. ><?php
  24706. $i = 0;
  24707. do {
  24708.     echo $i;
  24709. } while ($i > 0);
  24710. ?></PRE
  24711. ></TD
  24712. ></TR
  24713. ></TABLE
  24714. ><P
  24715. ></P
  24716. ></DIV
  24717. >
  24718.    </P
  24719. ><P
  24720. >      The above loop would run one time exactly, since after the first
  24721.      iteration, when truth expression is checked, it evaluates to
  24722.      <TT
  24723. CLASS="constant"
  24724. ><B
  24725. >FALSE</B
  24726. ></TT
  24727. > ($i is not bigger than 0) and the loop
  24728.      execution ends.
  24729.    </P
  24730. ><P
  24731. >     Advanced C users may be familiar with a different usage of the
  24732.     <VAR
  24733. CLASS="literal"
  24734. >do-while</VAR
  24735. > loop, to allow stopping execution in
  24736.     the middle of code blocks, by encapsulating them with
  24737.     <VAR
  24738. CLASS="literal"
  24739. >do-while</VAR
  24740. > (0), and using the <A
  24741. HREF="#control-structures.break"
  24742. ><VAR
  24743. CLASS="literal"
  24744. >break</VAR
  24745. ></A
  24746. >
  24747.     statement.  The following code fragment demonstrates this:
  24748.     <DIV
  24749. CLASS="informalexample"
  24750. ><P
  24751. ></P
  24752. ><A
  24753. NAME="AEN4512"
  24754. ></A
  24755. ><TABLE
  24756. BORDER="0"
  24757. BGCOLOR="#E0E0E0"
  24758. CELLPADDING="5"
  24759. ><TR
  24760. ><TD
  24761. ><PRE
  24762. CLASS="php"
  24763. ><?php
  24764. do {
  24765.     if ($i < 5) {
  24766.         echo "i is not big enough";
  24767.         break;
  24768.     }
  24769.     $i *= $factor;
  24770.     if ($i < $minimum_limit) {
  24771.         break;
  24772.     }
  24773.    echo "i is ok";
  24774.  
  24775.     /* process i */
  24776.  
  24777. } while (0);
  24778. ?></PRE
  24779. ></TD
  24780. ></TR
  24781. ></TABLE
  24782. ><P
  24783. ></P
  24784. ></DIV
  24785. >
  24786.    </P
  24787. ><P
  24788. >     Don't worry if you don't understand this right away or at all.
  24789.     You can code scripts and even powerful scripts without using this
  24790.     'feature'.
  24791.    </P
  24792. ></DIV
  24793. ><DIV
  24794. CLASS="sect1"
  24795. ><HR><H2
  24796. CLASS="sect1"
  24797. ><A
  24798. NAME="control-structures.for"
  24799. ><VAR
  24800. CLASS="literal"
  24801. >for</VAR
  24802. ></A
  24803. ></H2
  24804. ><P
  24805. >     <VAR
  24806. CLASS="literal"
  24807. >for</VAR
  24808. > loops are the most complex loops in PHP.
  24809.     They behave like their C counterparts.  The syntax of a
  24810.     <VAR
  24811. CLASS="literal"
  24812. >for</VAR
  24813. > loop is:
  24814.     <DIV
  24815. CLASS="informalexample"
  24816. ><P
  24817. ></P
  24818. ><A
  24819. NAME="AEN4521"
  24820. ></A
  24821. ><TABLE
  24822. BORDER="0"
  24823. BGCOLOR="#E0E0E0"
  24824. CELLPADDING="5"
  24825. ><TR
  24826. ><TD
  24827. ><PRE
  24828. CLASS="programlisting"
  24829. >for (expr1; expr2; expr3)
  24830.     statement</PRE
  24831. ></TD
  24832. ></TR
  24833. ></TABLE
  24834. ><P
  24835. ></P
  24836. ></DIV
  24837. >
  24838.    </P
  24839. ><P
  24840. >     The first expression (<VAR
  24841. CLASS="varname"
  24842. >expr1</VAR
  24843. >) is
  24844.     evaluated (executed) once unconditionally at the beginning of the
  24845.     loop.
  24846.    </P
  24847. ><P
  24848. >     In the beginning of each iteration,
  24849.     <VAR
  24850. CLASS="varname"
  24851. >expr2</VAR
  24852. > is evaluated.  If it evaluates to
  24853.     <TT
  24854. CLASS="constant"
  24855. ><B
  24856. >TRUE</B
  24857. ></TT
  24858. >, the loop continues and the nested
  24859.     statement(s) are executed.  If it evaluates to
  24860.     <TT
  24861. CLASS="constant"
  24862. ><B
  24863. >FALSE</B
  24864. ></TT
  24865. >, the execution of the loop ends.
  24866.    </P
  24867. ><P
  24868. >     At the end of each iteration, <VAR
  24869. CLASS="varname"
  24870. >expr3</VAR
  24871. > is
  24872.     evaluated (executed).
  24873.    </P
  24874. ><P
  24875. >     Each of the expressions can be empty.
  24876.     <VAR
  24877. CLASS="varname"
  24878. >expr2</VAR
  24879. > being empty means the loop should
  24880.     be run indefinitely (PHP implicitly considers it as
  24881.     <TT
  24882. CLASS="constant"
  24883. ><B
  24884. >TRUE</B
  24885. ></TT
  24886. >, like C).  This may not be as useless as
  24887.     you might think, since often you'd want to end the loop using a
  24888.     conditional <A
  24889. HREF="#control-structures.break"
  24890. ><VAR
  24891. CLASS="literal"
  24892. >break</VAR
  24893. ></A
  24894. >
  24895.     statement instead of using the <VAR
  24896. CLASS="literal"
  24897. >for</VAR
  24898. > truth
  24899.     expression.
  24900.    </P
  24901. ><P
  24902. >     Consider the following examples.  All of them display numbers from
  24903.     1 to 10:
  24904.     <DIV
  24905. CLASS="informalexample"
  24906. ><P
  24907. ></P
  24908. ><A
  24909. NAME="AEN4538"
  24910. ></A
  24911. ><TABLE
  24912. BORDER="0"
  24913. BGCOLOR="#E0E0E0"
  24914. CELLPADDING="5"
  24915. ><TR
  24916. ><TD
  24917. ><PRE
  24918. CLASS="php"
  24919. ><?php
  24920. /* example 1 */
  24921.  
  24922. for ($i = 1; $i <= 10; $i++) {
  24923.     echo $i;
  24924. }
  24925.  
  24926. /* example 2 */
  24927.  
  24928. for ($i = 1; ; $i++) {
  24929.     if ($i > 10) {
  24930.         break;
  24931.     }
  24932.     echo $i;
  24933. }
  24934.  
  24935. /* example 3 */
  24936.  
  24937. $i = 1;
  24938. for (; ; ) {
  24939.     if ($i > 10) {
  24940.         break;
  24941.     }
  24942.     echo $i;
  24943.     $i++;
  24944. }
  24945.  
  24946. /* example 4 */
  24947.  
  24948. for ($i = 1; $i <= 10; print $i, $i++);
  24949. ?></PRE
  24950. ></TD
  24951. ></TR
  24952. ></TABLE
  24953. ><P
  24954. ></P
  24955. ></DIV
  24956. >
  24957.    </P
  24958. ><P
  24959. >     Of course, the first example appears to be the nicest one (or
  24960.     perhaps the fourth), but you may find that being able to use empty
  24961.     expressions in <VAR
  24962. CLASS="literal"
  24963. >for</VAR
  24964. > loops comes in handy in many
  24965.     occasions.
  24966.    </P
  24967. ><P
  24968. >     PHP also supports the alternate "colon syntax" for
  24969.     <VAR
  24970. CLASS="literal"
  24971. >for</VAR
  24972. > loops.
  24973.     <DIV
  24974. CLASS="informalexample"
  24975. ><P
  24976. ></P
  24977. ><A
  24978. NAME="AEN4544"
  24979. ></A
  24980. ><TABLE
  24981. BORDER="0"
  24982. BGCOLOR="#E0E0E0"
  24983. CELLPADDING="5"
  24984. ><TR
  24985. ><TD
  24986. ><PRE
  24987. CLASS="programlisting"
  24988. >for (expr1; expr2; expr3):
  24989.     statement
  24990.     ...
  24991. endfor;</PRE
  24992. ></TD
  24993. ></TR
  24994. ></TABLE
  24995. ><P
  24996. ></P
  24997. ></DIV
  24998. >
  24999.    </P
  25000. ></DIV
  25001. ><DIV
  25002. CLASS="sect1"
  25003. ><HR><H2
  25004. CLASS="sect1"
  25005. ><A
  25006. NAME="control-structures.foreach"
  25007. ><VAR
  25008. CLASS="literal"
  25009. >foreach</VAR
  25010. ></A
  25011. ></H2
  25012. ><P
  25013. >     PHP 4 introduced a <VAR
  25014. CLASS="literal"
  25015. >foreach</VAR
  25016. > construct, much
  25017.     like Perl and some other languages. This simply gives an easy way to
  25018.     iterate over arrays. <VAR
  25019. CLASS="literal"
  25020. >foreach</VAR
  25021. > works only on arrays, and
  25022.     will issue an error when you try to use it on a variable with a different
  25023.     data type or an uninitialized variable. There are two syntaxes; the
  25024.     second is a minor but useful extension of the first:
  25025.     <DIV
  25026. CLASS="informalexample"
  25027. ><P
  25028. ></P
  25029. ><A
  25030. NAME="AEN4552"
  25031. ></A
  25032. ><TABLE
  25033. BORDER="0"
  25034. BGCOLOR="#E0E0E0"
  25035. CELLPADDING="5"
  25036. ><TR
  25037. ><TD
  25038. ><PRE
  25039. CLASS="programlisting"
  25040. >foreach (array_expression as $value)
  25041.     statement
  25042. foreach (array_expression as $key => $value)
  25043.     statement</PRE
  25044. ></TD
  25045. ></TR
  25046. ></TABLE
  25047. ><P
  25048. ></P
  25049. ></DIV
  25050. >
  25051.    </P
  25052. ><P
  25053. >     The first form loops over the array given by
  25054.     <VAR
  25055. CLASS="literal"
  25056. >array_expression</VAR
  25057. >. On each loop, the value of
  25058.     the current element is assigned to <VAR
  25059. CLASS="literal"
  25060. >$value</VAR
  25061. > and
  25062.     the internal array pointer is advanced by one (so on the next
  25063.     loop, you'll be looking at the next element).
  25064.    </P
  25065. ><P
  25066. >     The second form does the same thing, except that the current
  25067.     element's key will be assigned to the variable
  25068.     <VAR
  25069. CLASS="literal"
  25070. >$key</VAR
  25071. > on each loop.
  25072.    </P
  25073. ><P
  25074. >     <DIV
  25075. CLASS="note"
  25076. ><BLOCKQUOTE
  25077. CLASS="note"
  25078. ><P
  25079. ><B
  25080. >Note: </B
  25081. >
  25082.       When <VAR
  25083. CLASS="literal"
  25084. >foreach</VAR
  25085. > first starts executing, the
  25086.       internal array pointer is automatically reset to the first element
  25087.       of the array. This means that you do not need to call
  25088.       <A
  25089. HREF="#function.reset"
  25090. ><B
  25091. CLASS="function"
  25092. >reset()</B
  25093. ></A
  25094. > before a <VAR
  25095. CLASS="literal"
  25096. >foreach</VAR
  25097. >
  25098.       loop.
  25099.      </P
  25100. ></BLOCKQUOTE
  25101. ></DIV
  25102. >
  25103.    </P
  25104. ><P
  25105. >     <DIV
  25106. CLASS="note"
  25107. ><BLOCKQUOTE
  25108. CLASS="note"
  25109. ><P
  25110. ><B
  25111. >Note: </B
  25112. >
  25113.       Also note that <VAR
  25114. CLASS="literal"
  25115. >foreach</VAR
  25116. > operates on a copy of
  25117.       the specified array and not the array itself. Therefore, the
  25118.       array pointer is not modified as with the
  25119.       <A
  25120. HREF="#function.each"
  25121. ><B
  25122. CLASS="function"
  25123. >each()</B
  25124. ></A
  25125. > construct, and changes to the array
  25126.       element returned are not reflected in the original array.
  25127.       However, the internal pointer of the original array
  25128.       <SPAN
  25129. CLASS="emphasis"
  25130. ><I
  25131. CLASS="emphasis"
  25132. >is</I
  25133. ></SPAN
  25134. > advanced with the processing of the
  25135.       array.  Assuming the foreach loop runs to completion, the
  25136.       array's internal pointer will be at the end of the array.
  25137.      </P
  25138. ><P
  25139. >       As of PHP 5, you can easily modify array's elements by preceding
  25140.       <VAR
  25141. CLASS="literal"
  25142. >$value</VAR
  25143. > with &. This will assign
  25144.       <A
  25145. HREF="#language.references"
  25146. >reference</A
  25147. > instead of copying
  25148.       the value.
  25149.       <DIV
  25150. CLASS="informalexample"
  25151. ><P
  25152. ></P
  25153. ><A
  25154. NAME="AEN4574"
  25155. ></A
  25156. ><TABLE
  25157. BORDER="0"
  25158. BGCOLOR="#E0E0E0"
  25159. CELLPADDING="5"
  25160. ><TR
  25161. ><TD
  25162. ><PRE
  25163. CLASS="php"
  25164. ><?php
  25165. $arr = array(1, 2, 3, 4);
  25166. foreach ($arr as &$value) {
  25167.     $value = $value * 2;
  25168. }
  25169. // $arr is now array(2, 4, 6, 8)
  25170. ?></PRE
  25171. ></TD
  25172. ></TR
  25173. ></TABLE
  25174. ><P
  25175. ></P
  25176. ></DIV
  25177. >
  25178.       This is possible only if iterated array can be referenced (i.e. is
  25179.       variable).
  25180.      </P
  25181. ></BLOCKQUOTE
  25182. ></DIV
  25183. >
  25184.    </P
  25185. ><P
  25186. >     <DIV
  25187. CLASS="note"
  25188. ><BLOCKQUOTE
  25189. CLASS="note"
  25190. ><P
  25191. ><B
  25192. >Note: </B
  25193. >
  25194.       <VAR
  25195. CLASS="literal"
  25196. >foreach</VAR
  25197. > does not support the ability to
  25198.       suppress error messages using '@'.
  25199.      </P
  25200. ></BLOCKQUOTE
  25201. ></DIV
  25202. >
  25203.    </P
  25204. ><P
  25205. >     You may have noticed that the following are functionally
  25206.     identical:
  25207.     <DIV
  25208. CLASS="informalexample"
  25209. ><P
  25210. ></P
  25211. ><A
  25212. NAME="AEN4581"
  25213. ></A
  25214. ><TABLE
  25215. BORDER="0"
  25216. BGCOLOR="#E0E0E0"
  25217. CELLPADDING="5"
  25218. ><TR
  25219. ><TD
  25220. ><PRE
  25221. CLASS="php"
  25222. ><?php
  25223. $arr = array("one", "two", "three");
  25224. reset($arr);
  25225. while (list(, $value) = each($arr)) {
  25226.     echo "Value: $value<br />\n";
  25227. }
  25228.  
  25229. foreach ($arr as $value) {
  25230.     echo "Value: $value<br />\n";
  25231. }
  25232. ?></PRE
  25233. ></TD
  25234. ></TR
  25235. ></TABLE
  25236. ><P
  25237. ></P
  25238. ></DIV
  25239. >
  25240.     The following are also functionally identical:
  25241.     <DIV
  25242. CLASS="informalexample"
  25243. ><P
  25244. ></P
  25245. ><A
  25246. NAME="AEN4583"
  25247. ></A
  25248. ><TABLE
  25249. BORDER="0"
  25250. BGCOLOR="#E0E0E0"
  25251. CELLPADDING="5"
  25252. ><TR
  25253. ><TD
  25254. ><PRE
  25255. CLASS="php"
  25256. ><?php
  25257. $arr = array("one", "two", "three");
  25258. reset($arr);
  25259. while (list($key, $value) = each($arr)) {
  25260.     echo "Key: $key; Value: $value<br />\n";
  25261. }
  25262.  
  25263. foreach ($arr as $key => $value) {
  25264.     echo "Key: $key; Value: $value<br />\n";
  25265. }
  25266. ?></PRE
  25267. ></TD
  25268. ></TR
  25269. ></TABLE
  25270. ><P
  25271. ></P
  25272. ></DIV
  25273. >
  25274.    </P
  25275. ><P
  25276. >     Some more examples to demonstrate usages:
  25277.     <DIV
  25278. CLASS="informalexample"
  25279. ><P
  25280. ></P
  25281. ><A
  25282. NAME="AEN4586"
  25283. ></A
  25284. ><TABLE
  25285. BORDER="0"
  25286. BGCOLOR="#E0E0E0"
  25287. CELLPADDING="5"
  25288. ><TR
  25289. ><TD
  25290. ><PRE
  25291. CLASS="php"
  25292. ><?php
  25293. /* foreach example 1: value only */
  25294.  
  25295. $a = array(1, 2, 3, 17);
  25296.  
  25297. foreach ($a as $v) {
  25298.    echo "Current value of \$a: $v.\n";
  25299. }
  25300.  
  25301. /* foreach example 2: value (with key printed for illustration) */
  25302.  
  25303. $a = array(1, 2, 3, 17);
  25304.  
  25305. $i = 0; /* for illustrative purposes only */
  25306.  
  25307. foreach ($a as $v) {
  25308.     echo "\$a[$i] => $v.\n";
  25309.     $i++;
  25310. }
  25311.  
  25312. /* foreach example 3: key and value */
  25313.  
  25314. $a = array(
  25315.     "one" => 1,
  25316.     "two" => 2,
  25317.     "three" => 3,
  25318.     "seventeen" => 17
  25319. );
  25320.  
  25321. foreach ($a as $k => $v) {
  25322.     echo "\$a[$k] => $v.\n";
  25323. }
  25324.  
  25325. /* foreach example 4: multi-dimensional arrays */
  25326. $a = array();
  25327. $a[0][0] = "a";
  25328. $a[0][1] = "b";
  25329. $a[1][0] = "y";
  25330. $a[1][1] = "z";
  25331.  
  25332. foreach ($a as $v1) {
  25333.     foreach ($v1 as $v2) {
  25334.         echo "$v2\n";
  25335.     }
  25336. }
  25337.  
  25338. /* foreach example 5: dynamic arrays */
  25339.  
  25340. foreach (array(1, 2, 3, 4, 5) as $v) {
  25341.     echo "$v\n";
  25342. }
  25343. ?></PRE
  25344. ></TD
  25345. ></TR
  25346. ></TABLE
  25347. ><P
  25348. ></P
  25349. ></DIV
  25350. >
  25351.    </P
  25352. ></DIV
  25353. ><DIV
  25354. CLASS="sect1"
  25355. ><HR><H2
  25356. CLASS="sect1"
  25357. ><A
  25358. NAME="control-structures.break"
  25359. ><VAR
  25360. CLASS="literal"
  25361. >break</VAR
  25362. ></A
  25363. ></H2
  25364. ><P
  25365. >     <VAR
  25366. CLASS="literal"
  25367. >break</VAR
  25368. > ends execution of the current
  25369.     <VAR
  25370. CLASS="literal"
  25371. >for</VAR
  25372. >, <VAR
  25373. CLASS="literal"
  25374. >foreach</VAR
  25375. >,
  25376.     <VAR
  25377. CLASS="literal"
  25378. >while</VAR
  25379. >, <VAR
  25380. CLASS="literal"
  25381. >do-while</VAR
  25382. > or
  25383.     <VAR
  25384. CLASS="literal"
  25385. >switch</VAR
  25386. > structure.
  25387.    </P
  25388. ><P
  25389. >     <VAR
  25390. CLASS="literal"
  25391. >break</VAR
  25392. > accepts an optional numeric argument
  25393.     which tells it how many nested enclosing structures are to be
  25394.     broken out of.
  25395.    </P
  25396. ><P
  25397. >     <DIV
  25398. CLASS="informalexample"
  25399. ><P
  25400. ></P
  25401. ><A
  25402. NAME="AEN4601"
  25403. ></A
  25404. ><TABLE
  25405. BORDER="0"
  25406. BGCOLOR="#E0E0E0"
  25407. CELLPADDING="5"
  25408. ><TR
  25409. ><TD
  25410. ><PRE
  25411. CLASS="php"
  25412. ><?php
  25413. $arr = array('one', 'two', 'three', 'four', 'stop', 'five');
  25414. while (list(, $val) = each($arr)) {
  25415.     if ($val == 'stop') {
  25416.         break;    /* You could also write 'break 1;' here. */
  25417.     }
  25418.     echo "$val<br />\n";
  25419. }
  25420.  
  25421. /* Using the optional argument. */
  25422.  
  25423. $i = 0;
  25424. while (++$i) {
  25425.     switch ($i) {
  25426.     case 5:
  25427.         echo "At 5<br />\n";
  25428.         break 1;  /* Exit only the switch. */
  25429.     case 10:
  25430.         echo "At 10; quitting<br />\n";
  25431.         break 2;  /* Exit the switch and the while. */
  25432.     default:
  25433.         break;
  25434.     }
  25435. }
  25436. ?></PRE
  25437. ></TD
  25438. ></TR
  25439. ></TABLE
  25440. ><P
  25441. ></P
  25442. ></DIV
  25443. >
  25444.    </P
  25445. ></DIV
  25446. ><DIV
  25447. CLASS="sect1"
  25448. ><HR><H2
  25449. CLASS="sect1"
  25450. ><A
  25451. NAME="control-structures.continue"
  25452. ><VAR
  25453. CLASS="literal"
  25454. >continue</VAR
  25455. ></A
  25456. ></H2
  25457. ><P
  25458. >     <VAR
  25459. CLASS="literal"
  25460. >continue</VAR
  25461. > is used within looping structures to
  25462.     skip the rest of the current loop iteration and continue execution
  25463.     at the beginning of the next iteration.
  25464.    </P
  25465. ><DIV
  25466. CLASS="note"
  25467. ><BLOCKQUOTE
  25468. CLASS="note"
  25469. ><P
  25470. ><B
  25471. >Note: </B
  25472. >
  25473.      Note that in PHP the
  25474.      <A
  25475. HREF="#control-structures.switch"
  25476. >switch</A
  25477. > statement is
  25478.      considered a looping structure for the purposes of
  25479.      <VAR
  25480. CLASS="literal"
  25481. >continue</VAR
  25482. >.
  25483.     </P
  25484. ></BLOCKQUOTE
  25485. ></DIV
  25486. ><P
  25487. >     <VAR
  25488. CLASS="literal"
  25489. >continue</VAR
  25490. > accepts an optional numeric argument
  25491.     which tells it how many levels of enclosing loops it should skip
  25492.     to the end of.
  25493.    </P
  25494. ><P
  25495. >     <DIV
  25496. CLASS="informalexample"
  25497. ><P
  25498. ></P
  25499. ><A
  25500. NAME="AEN4615"
  25501. ></A
  25502. ><TABLE
  25503. BORDER="0"
  25504. BGCOLOR="#E0E0E0"
  25505. CELLPADDING="5"
  25506. ><TR
  25507. ><TD
  25508. ><PRE
  25509. CLASS="php"
  25510. ><?php
  25511. while (list($key, $value) = each($arr)) {
  25512.     if (!($key % 2)) { // skip odd members
  25513.         continue;
  25514.     }
  25515.     do_something_odd($value);
  25516. }
  25517.  
  25518. $i = 0;
  25519. while ($i++ < 5) {
  25520.     echo "Outer<br />\n";
  25521.     while (1) {
  25522.         echo "&nbsp;&nbsp;Middle<br />\n";
  25523.         while (1) {
  25524.             echo "&nbsp;&nbsp;Inner<br />\n";
  25525.             continue 3;
  25526.         }
  25527.         echo "This never gets output.<br />\n";
  25528.     }
  25529.     echo "Neither does this.<br />\n";
  25530. }
  25531. ?></PRE
  25532. ></TD
  25533. ></TR
  25534. ></TABLE
  25535. ><P
  25536. ></P
  25537. ></DIV
  25538. >
  25539.     </P
  25540. ><P
  25541. >      Omitting the semicolon after <VAR
  25542. CLASS="literal"
  25543. >continue</VAR
  25544. > can lead to
  25545.      confusion. Here's an example of what you shouldn't do. 
  25546.     </P
  25547. ><P
  25548. >      <DIV
  25549. CLASS="informalexample"
  25550. ><P
  25551. ></P
  25552. ><A
  25553. NAME="AEN4620"
  25554. ></A
  25555. ><TABLE
  25556. BORDER="0"
  25557. BGCOLOR="#E0E0E0"
  25558. CELLPADDING="5"
  25559. ><TR
  25560. ><TD
  25561. ><PRE
  25562. CLASS="php"
  25563. ><?php
  25564.   for ($i = 0; $i < 5; ++$i) {
  25565.       if ($i == 2)
  25566.           continue
  25567.       print "$i\n";
  25568.   }
  25569. ?></PRE
  25570. ></TD
  25571. ></TR
  25572. ></TABLE
  25573. ><P
  25574. >        One can expect the result to be :
  25575.       </P
  25576. ><TABLE
  25577. BORDER="0"
  25578. BGCOLOR="#E0E0E0"
  25579. CELLPADDING="5"
  25580. ><TR
  25581. ><TD
  25582. ><PRE
  25583. CLASS="screen"
  25584. >0
  25585. 1
  25586. 3
  25587. 4</PRE
  25588. ></TD
  25589. ></TR
  25590. ></TABLE
  25591. ><P
  25592. >        but this script will output :
  25593.       </P
  25594. ><TABLE
  25595. BORDER="0"
  25596. BGCOLOR="#E0E0E0"
  25597. CELLPADDING="5"
  25598. ><TR
  25599. ><TD
  25600. ><PRE
  25601. CLASS="screen"
  25602. >2</PRE
  25603. ></TD
  25604. ></TR
  25605. ></TABLE
  25606. ><P
  25607. >        because the return value of the <A
  25608. HREF="#function.print"
  25609. ><B
  25610. CLASS="function"
  25611. >print()</B
  25612. ></A
  25613. >
  25614.        call is <VAR
  25615. CLASS="literal"
  25616. >int(1)</VAR
  25617. >, and it will look like the
  25618.        optional numeric argument mentioned above.
  25619.       </P
  25620. ><P
  25621. ></P
  25622. ></DIV
  25623. >
  25624.     </P
  25625. ></DIV
  25626. ><DIV
  25627. CLASS="sect1"
  25628. ><HR><H2
  25629. CLASS="sect1"
  25630. ><A
  25631. NAME="control-structures.switch"
  25632. ><VAR
  25633. CLASS="literal"
  25634. >switch</VAR
  25635. ></A
  25636. ></H2
  25637. ><P
  25638. >     The <VAR
  25639. CLASS="literal"
  25640. >switch</VAR
  25641. > statement is similar to a series of
  25642.     IF statements on the same expression.  In many occasions, you may
  25643.     want to compare the same variable (or expression) with many
  25644.     different values, and execute a different piece of code depending
  25645.     on which value it equals to.  This is exactly what the
  25646.     <VAR
  25647. CLASS="literal"
  25648. >switch</VAR
  25649. > statement is for.
  25650.    </P
  25651. ><DIV
  25652. CLASS="note"
  25653. ><BLOCKQUOTE
  25654. CLASS="note"
  25655. ><P
  25656. ><B
  25657. >Note: </B
  25658. >
  25659.      Note that unlike some other languages, the
  25660.      <A
  25661. HREF="#control-structures.continue"
  25662. >continue</A
  25663. > statement
  25664.      applies to switch and acts similar to <VAR
  25665. CLASS="literal"
  25666. >break</VAR
  25667. >.  If you
  25668.      have a switch inside a loop and wish to continue to the next iteration of
  25669.      the outer loop, use <VAR
  25670. CLASS="literal"
  25671. >continue 2</VAR
  25672. >.
  25673.     </P
  25674. ></BLOCKQUOTE
  25675. ></DIV
  25676. ><P
  25677. >     The following two examples are two different ways to write the
  25678.     same thing, one using a series of <VAR
  25679. CLASS="literal"
  25680. >if</VAR
  25681. > and
  25682.     <VAR
  25683. CLASS="literal"
  25684. >elseif</VAR
  25685. > statements, and the other using the
  25686.     <VAR
  25687. CLASS="literal"
  25688. >switch</VAR
  25689. > statement:
  25690.     <TABLE
  25691. WIDTH="100%"
  25692. BORDER="0"
  25693. CELLPADDING="0"
  25694. CELLSPACING="0"
  25695. CLASS="EXAMPLE"
  25696. ><TR
  25697. ><TD
  25698. ><DIV
  25699. CLASS="example"
  25700. ><A
  25701. NAME="AEN4644"
  25702. ></A
  25703. ><P
  25704. ><B
  25705. >Example 16-1. <VAR
  25706. CLASS="literal"
  25707. >switch</VAR
  25708. > structure</B
  25709. ></P
  25710. ><TABLE
  25711. BORDER="0"
  25712. BGCOLOR="#E0E0E0"
  25713. CELLPADDING="5"
  25714. ><TR
  25715. ><TD
  25716. ><PRE
  25717. CLASS="php"
  25718. ><?php
  25719. if ($i == 0) {
  25720.     echo "i equals 0";
  25721. } elseif ($i == 1) {
  25722.     echo "i equals 1";
  25723. } elseif ($i == 2) {
  25724.     echo "i equals 2";
  25725. }
  25726.  
  25727. switch ($i) {
  25728. case 0:
  25729.     echo "i equals 0";
  25730.     break;
  25731. case 1:
  25732.     echo "i equals 1";
  25733.     break;
  25734. case 2:
  25735.     echo "i equals 2";
  25736.     break;
  25737. }
  25738. ?></PRE
  25739. ></TD
  25740. ></TR
  25741. ></TABLE
  25742. ></DIV
  25743. ></TD
  25744. ></TR
  25745. ></TABLE
  25746. >
  25747.     <TABLE
  25748. WIDTH="100%"
  25749. BORDER="0"
  25750. CELLPADDING="0"
  25751. CELLSPACING="0"
  25752. CLASS="EXAMPLE"
  25753. ><TR
  25754. ><TD
  25755. ><DIV
  25756. CLASS="example"
  25757. ><A
  25758. NAME="AEN4648"
  25759. ></A
  25760. ><P
  25761. ><B
  25762. >Example 16-2. <VAR
  25763. CLASS="literal"
  25764. >switch</VAR
  25765. > structure allows usage of strings</B
  25766. ></P
  25767. ><TABLE
  25768. BORDER="0"
  25769. BGCOLOR="#E0E0E0"
  25770. CELLPADDING="5"
  25771. ><TR
  25772. ><TD
  25773. ><PRE
  25774. CLASS="php"
  25775. ><?php
  25776. switch ($i) {
  25777. case "apple":
  25778.     echo "i is apple";
  25779.     break;
  25780. case "bar":
  25781.     echo "i is bar";
  25782.     break;
  25783. case "cake":
  25784.     echo "i is cake";
  25785.     break;
  25786. }
  25787. ?></PRE
  25788. ></TD
  25789. ></TR
  25790. ></TABLE
  25791. ></DIV
  25792. ></TD
  25793. ></TR
  25794. ></TABLE
  25795. >
  25796.    </P
  25797. ><P
  25798. >     It is important to understand how the <VAR
  25799. CLASS="literal"
  25800. >switch</VAR
  25801. >
  25802.     statement is executed in order to avoid mistakes.  The
  25803.     <VAR
  25804. CLASS="literal"
  25805. >switch</VAR
  25806. > statement executes line by line
  25807.     (actually, statement by statement).  In the beginning, no code is
  25808.     executed.  Only when a <VAR
  25809. CLASS="literal"
  25810. >case</VAR
  25811. > statement is found
  25812.     with a value that matches the value of the
  25813.     <VAR
  25814. CLASS="literal"
  25815. >switch</VAR
  25816. > expression does PHP begin to execute the
  25817.     statements.  PHP continues to execute the statements until the end
  25818.     of the <VAR
  25819. CLASS="literal"
  25820. >switch</VAR
  25821. > block, or the first time it sees
  25822.     a <VAR
  25823. CLASS="literal"
  25824. >break</VAR
  25825. > statement.  If you don't write a
  25826.     <VAR
  25827. CLASS="literal"
  25828. >break</VAR
  25829. > statement at the end of a case's
  25830.     statement list, PHP will go on executing the statements of the
  25831.     following case.  For example:
  25832.     <DIV
  25833. CLASS="informalexample"
  25834. ><P
  25835. ></P
  25836. ><A
  25837. NAME="AEN4660"
  25838. ></A
  25839. ><TABLE
  25840. BORDER="0"
  25841. BGCOLOR="#E0E0E0"
  25842. CELLPADDING="5"
  25843. ><TR
  25844. ><TD
  25845. ><PRE
  25846. CLASS="php"
  25847. ><?php
  25848. switch ($i) {
  25849. case 0:
  25850.     echo "i equals 0";
  25851. case 1:
  25852.     echo "i equals 1";
  25853. case 2:
  25854.     echo "i equals 2";
  25855. }
  25856. ?></PRE
  25857. ></TD
  25858. ></TR
  25859. ></TABLE
  25860. ><P
  25861. ></P
  25862. ></DIV
  25863. >
  25864.    </P
  25865. ><P
  25866. >     Here, if <VAR
  25867. CLASS="varname"
  25868. >$i</VAR
  25869. > is equal to 0, PHP would execute all of the echo
  25870.     statements!  If <VAR
  25871. CLASS="varname"
  25872. >$i</VAR
  25873. > is equal to 1, PHP would execute the last two
  25874.     echo statements. You would get the expected behavior ('i equals 2' 
  25875.     would be displayed) only if <VAR
  25876. CLASS="varname"
  25877. >$i</VAR
  25878. > is equal to 2.  Thus,
  25879.     it is important not to forget <VAR
  25880. CLASS="literal"
  25881. >break</VAR
  25882. > statements
  25883.     (even though you may want to avoid supplying them on purpose under
  25884.     certain circumstances).
  25885.    </P
  25886. ><P
  25887. >     In a <VAR
  25888. CLASS="literal"
  25889. >switch</VAR
  25890. > statement, the condition is
  25891.     evaluated only once and the result is compared to each
  25892.     <VAR
  25893. CLASS="literal"
  25894. >case</VAR
  25895. > statement. In an <VAR
  25896. CLASS="literal"
  25897. >elseif</VAR
  25898. >
  25899.     statement, the condition is evaluated again. If your condition is
  25900.     more complicated than a simple compare and/or is in a tight loop,
  25901.     a <VAR
  25902. CLASS="literal"
  25903. >switch</VAR
  25904. > may be faster.
  25905.    </P
  25906. ><P
  25907. >     The statement list for a case can also be empty, which simply
  25908.     passes control into the statement list for the next case.
  25909.     <DIV
  25910. CLASS="informalexample"
  25911. ><P
  25912. ></P
  25913. ><A
  25914. NAME="AEN4673"
  25915. ></A
  25916. ><TABLE
  25917. BORDER="0"
  25918. BGCOLOR="#E0E0E0"
  25919. CELLPADDING="5"
  25920. ><TR
  25921. ><TD
  25922. ><PRE
  25923. CLASS="php"
  25924. ><?php
  25925. switch ($i) {
  25926. case 0:
  25927. case 1:
  25928. case 2:
  25929.     echo "i is less than 3 but not negative";
  25930.     break;
  25931. case 3:
  25932.     echo "i is 3";
  25933. }
  25934. ?></PRE
  25935. ></TD
  25936. ></TR
  25937. ></TABLE
  25938. ><P
  25939. ></P
  25940. ></DIV
  25941. >
  25942.    </P
  25943. ><P
  25944. >     A special case is the <VAR
  25945. CLASS="literal"
  25946. >default</VAR
  25947. > case.  This case matches
  25948.     anything that wasn't matched by the other cases, and should be the last
  25949.     <VAR
  25950. CLASS="literal"
  25951. >case</VAR
  25952. > statement.  For example:
  25953.     <DIV
  25954. CLASS="informalexample"
  25955. ><P
  25956. ></P
  25957. ><A
  25958. NAME="AEN4678"
  25959. ></A
  25960. ><TABLE
  25961. BORDER="0"
  25962. BGCOLOR="#E0E0E0"
  25963. CELLPADDING="5"
  25964. ><TR
  25965. ><TD
  25966. ><PRE
  25967. CLASS="php"
  25968. ><?php
  25969. switch ($i) {
  25970. case 0:
  25971.     echo "i equals 0";
  25972.     break;
  25973. case 1:
  25974.     echo "i equals 1";
  25975.     break;
  25976. case 2:
  25977.     echo "i equals 2";
  25978.     break;
  25979. default:
  25980.     echo "i is not equal to 0, 1 or 2";
  25981. }
  25982. ?></PRE
  25983. ></TD
  25984. ></TR
  25985. ></TABLE
  25986. ><P
  25987. ></P
  25988. ></DIV
  25989. >
  25990.    </P
  25991. ><P
  25992. >     The <VAR
  25993. CLASS="literal"
  25994. >case</VAR
  25995. > expression may be any expression that
  25996.     evaluates to a simple type, that is, integer or floating-point
  25997.     numbers and strings.  Arrays or objects cannot be used here unless
  25998.     they are dereferenced to a simple type.
  25999.    </P
  26000. ><P
  26001. >     The alternative syntax for control structures is supported with
  26002.     switches. For more information, see <A
  26003. HREF="#control-structures.alternative-syntax"
  26004. >Alternative syntax
  26005.     for control structures</A
  26006. > .
  26007.     <DIV
  26008. CLASS="informalexample"
  26009. ><P
  26010. ></P
  26011. ><A
  26012. NAME="AEN4684"
  26013. ></A
  26014. ><TABLE
  26015. BORDER="0"
  26016. BGCOLOR="#E0E0E0"
  26017. CELLPADDING="5"
  26018. ><TR
  26019. ><TD
  26020. ><PRE
  26021. CLASS="php"
  26022. ><?php
  26023. switch ($i):
  26024. case 0:
  26025.     echo "i equals 0";
  26026.     break;
  26027. case 1:
  26028.     echo "i equals 1";
  26029.     break;
  26030. case 2:
  26031.     echo "i equals 2";
  26032.     break;
  26033. default:
  26034.     echo "i is not equal to 0, 1 or 2";
  26035. endswitch;
  26036. ?></PRE
  26037. ></TD
  26038. ></TR
  26039. ></TABLE
  26040. ><P
  26041. ></P
  26042. ></DIV
  26043. >
  26044.    </P
  26045. ></DIV
  26046. ><DIV
  26047. CLASS="sect1"
  26048. ><HR><H2
  26049. CLASS="sect1"
  26050. ><A
  26051. NAME="control-structures.declare"
  26052. ><VAR
  26053. CLASS="literal"
  26054. >declare</VAR
  26055. ></A
  26056. ></H2
  26057. ><P
  26058. >     The <VAR
  26059. CLASS="literal"
  26060. >declare</VAR
  26061. > construct is used to
  26062.     set execution directives for a block of code.
  26063.     The syntax of <VAR
  26064. CLASS="literal"
  26065. >declare</VAR
  26066. > is similar to
  26067.     the syntax of other flow control constructs:
  26068.     <DIV
  26069. CLASS="informalexample"
  26070. ><P
  26071. ></P
  26072. ><A
  26073. NAME="AEN4692"
  26074. ></A
  26075. ><TABLE
  26076. BORDER="0"
  26077. BGCOLOR="#E0E0E0"
  26078. CELLPADDING="5"
  26079. ><TR
  26080. ><TD
  26081. ><PRE
  26082. CLASS="programlisting"
  26083. >declare (directive)
  26084.     statement</PRE
  26085. ></TD
  26086. ></TR
  26087. ></TABLE
  26088. ><P
  26089. ></P
  26090. ></DIV
  26091. >
  26092.    </P
  26093. ><P
  26094. >     The <VAR
  26095. CLASS="literal"
  26096. >directive</VAR
  26097. > section allows the
  26098.     behavior of the <VAR
  26099. CLASS="literal"
  26100. >declare</VAR
  26101. > block to
  26102.     be set.
  26103.     Currently only one directive is recognized: the
  26104.     <VAR
  26105. CLASS="literal"
  26106. >ticks</VAR
  26107. > directive. (See below for more
  26108.     information on the
  26109.     <A
  26110. HREF="#control-structures.declare.ticks"
  26111. >ticks</A
  26112. >
  26113.     directive)
  26114.    </P
  26115. ><P
  26116. >     The <VAR
  26117. CLASS="literal"
  26118. >statement</VAR
  26119. > part of the
  26120.     <VAR
  26121. CLASS="literal"
  26122. >declare</VAR
  26123. > block will be executed -- how
  26124.     it is executed and what side effects occur during execution
  26125.     may depend on the directive set in the
  26126.     <VAR
  26127. CLASS="literal"
  26128. >directive</VAR
  26129. > block.
  26130.    </P
  26131. ><P
  26132. >     The <VAR
  26133. CLASS="literal"
  26134. >declare</VAR
  26135. > construct can also be used in the global 
  26136.     scope, affecting all code following it.
  26137.     <DIV
  26138. CLASS="informalexample"
  26139. ><P
  26140. ></P
  26141. ><A
  26142. NAME="AEN4705"
  26143. ></A
  26144. ><TABLE
  26145. BORDER="0"
  26146. BGCOLOR="#E0E0E0"
  26147. CELLPADDING="5"
  26148. ><TR
  26149. ><TD
  26150. ><PRE
  26151. CLASS="php"
  26152. ><?php
  26153. // these are the same:
  26154.  
  26155. // you can use this:
  26156. declare(ticks=1) {
  26157.     // entire script here
  26158. }
  26159.  
  26160. // or you can use this:
  26161. declare(ticks=1);
  26162. // entire script here
  26163. ?></PRE
  26164. ></TD
  26165. ></TR
  26166. ></TABLE
  26167. ><P
  26168. ></P
  26169. ></DIV
  26170. >
  26171.    </P
  26172. ><DIV
  26173. CLASS="sect2"
  26174. ><HR><H3
  26175. CLASS="sect2"
  26176. ><A
  26177. NAME="control-structures.declare.ticks"
  26178. >Ticks</A
  26179. ></H3
  26180. ><P
  26181. >A tick is an event that occurs for every
  26182.     <VAR
  26183. CLASS="varname"
  26184. >N</VAR
  26185. > low-level statements executed
  26186.     by the parser within the <VAR
  26187. CLASS="literal"
  26188. >declare</VAR
  26189. > block.
  26190.     The value for <VAR
  26191. CLASS="varname"
  26192. >N</VAR
  26193. > is specified
  26194.     using <VAR
  26195. CLASS="literal"
  26196. >ticks=<VAR
  26197. CLASS="varname"
  26198. >N</VAR
  26199. ></VAR
  26200. >
  26201.     within the <VAR
  26202. CLASS="literal"
  26203. >declare</VAR
  26204. > blocks's
  26205.     <VAR
  26206. CLASS="literal"
  26207. >directive</VAR
  26208. > section.
  26209.    </P
  26210. ><P
  26211. >     The event(s) that occur on each tick are specified using the
  26212.     <A
  26213. HREF="#function.register-tick-function"
  26214. ><B
  26215. CLASS="function"
  26216. >register_tick_function()</B
  26217. ></A
  26218. >. See the example 
  26219.     below for more details. Note that more than one event can occur
  26220.     for each tick.
  26221.    </P
  26222. ><P
  26223. >     <TABLE
  26224. WIDTH="100%"
  26225. BORDER="0"
  26226. CELLPADDING="0"
  26227. CELLSPACING="0"
  26228. CLASS="EXAMPLE"
  26229. ><TR
  26230. ><TD
  26231. ><DIV
  26232. CLASS="example"
  26233. ><A
  26234. NAME="AEN4720"
  26235. ></A
  26236. ><P
  26237. ><B
  26238. >Example 16-3. Profile a section of PHP code</B
  26239. ></P
  26240. ><TABLE
  26241. BORDER="0"
  26242. BGCOLOR="#E0E0E0"
  26243. CELLPADDING="5"
  26244. ><TR
  26245. ><TD
  26246. ><PRE
  26247. CLASS="php"
  26248. ><?php
  26249. // A function that records the time when it is called
  26250. function profile($dump = FALSE)
  26251. {
  26252.     static $profile;
  26253.  
  26254.     // Return the times stored in profile, then erase it
  26255.     if ($dump) {
  26256.         $temp = $profile;
  26257.         unset($profile);
  26258.         return($temp);
  26259.     }
  26260.  
  26261.     $profile[] = microtime();
  26262. }
  26263.  
  26264. // Set up a tick handler
  26265. register_tick_function("profile");
  26266.  
  26267. // Initialize the function before the declare block
  26268. profile();
  26269.  
  26270. // Run a block of code, throw a tick every 2nd statement
  26271. declare(ticks=2) {
  26272.     for ($x = 1; $x < 50; ++$x) {
  26273.         echo similar_text(md5($x), md5($x*$x)), "<br />;";
  26274.     }
  26275. }
  26276.  
  26277. // Display the data stored in the profiler
  26278. print_r(profile(TRUE));
  26279. ?></PRE
  26280. ></TD
  26281. ></TR
  26282. ></TABLE
  26283. ></DIV
  26284. ></TD
  26285. ></TR
  26286. ></TABLE
  26287. >
  26288.     The example profiles the PHP code within the 'declare'
  26289.     block, recording the time at which every second low-level
  26290.     statement in the block was executed. This information can
  26291.     then be used to find the slow areas within particular
  26292.     segments of code. This process can be performed using other
  26293.     methods: using ticks is more convenient and easier to
  26294.     implement.
  26295.    </P
  26296. ><P
  26297. >     Ticks are well suited for debugging, implementing simple
  26298.     multitasking, background I/O and many other tasks.
  26299.    </P
  26300. ><P
  26301. >     See also <A
  26302. HREF="#function.register-tick-function"
  26303. ><B
  26304. CLASS="function"
  26305. >register_tick_function()</B
  26306. ></A
  26307. > and
  26308.     <A
  26309. HREF="#function.unregister-tick-function"
  26310. ><B
  26311. CLASS="function"
  26312. >unregister_tick_function()</B
  26313. ></A
  26314. >.
  26315.    </P
  26316. ></DIV
  26317. ></DIV
  26318. ><DIV
  26319. CLASS="sect1"
  26320. ><HR><H2
  26321. CLASS="sect1"
  26322. ><A
  26323. NAME="function.return"
  26324. >return</A
  26325. ></H2
  26326. ><P
  26327. >     If called from within a function, the <A
  26328. HREF="#function.return"
  26329. ><B
  26330. CLASS="function"
  26331. >return()</B
  26332. ></A
  26333. >
  26334.     statement immediately ends execution of the current function, and
  26335.     returns its argument as the value of the function
  26336.     call. <A
  26337. HREF="#function.return"
  26338. ><B
  26339. CLASS="function"
  26340. >return()</B
  26341. ></A
  26342. > will also end the execution of
  26343.     an <A
  26344. HREF="#function.eval"
  26345. ><B
  26346. CLASS="function"
  26347. >eval()</B
  26348. ></A
  26349. > statement or script file.
  26350.    </P
  26351. ><P
  26352. >     If called from the global scope, then execution of the current
  26353.     script file is ended. If the current script file was
  26354.     <A
  26355. HREF="#function.include"
  26356. ><B
  26357. CLASS="function"
  26358. >include()</B
  26359. ></A
  26360. >ed or <A
  26361. HREF="#function.require"
  26362. ><B
  26363. CLASS="function"
  26364. >require()</B
  26365. ></A
  26366. >ed,
  26367.     then control is passed back to the calling file. Furthermore, if
  26368.     the current script file was <A
  26369. HREF="#function.include"
  26370. ><B
  26371. CLASS="function"
  26372. >include()</B
  26373. ></A
  26374. >ed, then
  26375.     the value given to <A
  26376. HREF="#function.return"
  26377. ><B
  26378. CLASS="function"
  26379. >return()</B
  26380. ></A
  26381. > will be returned as
  26382.     the value of the <A
  26383. HREF="#function.include"
  26384. ><B
  26385. CLASS="function"
  26386. >include()</B
  26387. ></A
  26388. > call. If
  26389.     <A
  26390. HREF="#function.return"
  26391. ><B
  26392. CLASS="function"
  26393. >return()</B
  26394. ></A
  26395. > is called from within the main script
  26396.     file, then script execution ends. If the current script file was
  26397.     named by the <A
  26398. HREF="#ini.auto-prepend-file"
  26399. >auto_prepend_file</A
  26400. > or <A
  26401. HREF="#ini.auto-append-file"
  26402. >auto_append_file</A
  26403. >
  26404.     configuration options in <TT
  26405. CLASS="filename"
  26406. >php.ini</TT
  26407. >, 
  26408.     then that script file's execution is ended.
  26409.    </P
  26410. ><P
  26411. >For more information, see <A
  26412. HREF="#functions.returning-values"
  26413. >Returning values</A
  26414. >.
  26415.    </P
  26416. ><P
  26417. >     <DIV
  26418. CLASS="note"
  26419. ><BLOCKQUOTE
  26420. CLASS="note"
  26421. ><P
  26422. ><B
  26423. >Note: </B
  26424. >
  26425.       Note that since <A
  26426. HREF="#function.return"
  26427. ><B
  26428. CLASS="function"
  26429. >return()</B
  26430. ></A
  26431. > is a language
  26432.       construct and not a function, the parentheses surrounding its
  26433.       arguments are <SPAN
  26434. CLASS="emphasis"
  26435. ><I
  26436. CLASS="emphasis"
  26437. >only</I
  26438. ></SPAN
  26439. > required if the argument
  26440.       contains an expression. It is common to leave them out while returning a variable.
  26441.      </P
  26442. ></BLOCKQUOTE
  26443. ></DIV
  26444. >
  26445.    </P
  26446. ></DIV
  26447. ><DIV
  26448. CLASS="sect1"
  26449. ><HR><H2
  26450. CLASS="sect1"
  26451. ><A
  26452. NAME="function.require"
  26453. ><A
  26454. HREF="#function.require"
  26455. ><B
  26456. CLASS="function"
  26457. >require()</B
  26458. ></A
  26459. ></A
  26460. ></H2
  26461. ><P
  26462. >     The <A
  26463. HREF="#function.require"
  26464. ><B
  26465. CLASS="function"
  26466. >require()</B
  26467. ></A
  26468. > statement includes and evaluates
  26469.     the specific file.
  26470.    </P
  26471. ><P
  26472. >      <A
  26473. HREF="#function.require"
  26474. ><B
  26475. CLASS="function"
  26476. >require()</B
  26477. ></A
  26478. > includes and evaluates a specific file.  
  26479.      Detailed information on how this inclusion works is described in the 
  26480.      documentation for <A
  26481. HREF="#function.include"
  26482. ><B
  26483. CLASS="function"
  26484. >include()</B
  26485. ></A
  26486. >.
  26487.    </P
  26488. ><P
  26489. >      <A
  26490. HREF="#function.require"
  26491. ><B
  26492. CLASS="function"
  26493. >require()</B
  26494. ></A
  26495. > and <A
  26496. HREF="#function.include"
  26497. ><B
  26498. CLASS="function"
  26499. >include()</B
  26500. ></A
  26501. > 
  26502.      are identical in every way except how they handle failure.  
  26503.      <A
  26504. HREF="#function.include"
  26505. ><B
  26506. CLASS="function"
  26507. >include()</B
  26508. ></A
  26509. > produces a 
  26510.      <A
  26511. HREF="#internal.e-warning"
  26512. >Warning</A
  26513. > while 
  26514.      <A
  26515. HREF="#function.require"
  26516. ><B
  26517. CLASS="function"
  26518. >require()</B
  26519. ></A
  26520. > results in a <A
  26521. HREF="#internal.e-error"
  26522. >      Fatal Error</A
  26523. >.  In other words, don't hesitate to use 
  26524.      <A
  26525. HREF="#function.require"
  26526. ><B
  26527. CLASS="function"
  26528. >require()</B
  26529. ></A
  26530. > if you want a missing file to halt processing 
  26531.      of the page.  <A
  26532. HREF="#function.include"
  26533. ><B
  26534. CLASS="function"
  26535. >include()</B
  26536. ></A
  26537. > does not behave this way, the
  26538.      script will continue regardless.  Be sure to have an appropriate
  26539.      <A
  26540. HREF="#ini.include-path"
  26541. >include_path</A
  26542. > setting as well.
  26543.    </P
  26544. ><P
  26545. >     <TABLE
  26546. WIDTH="100%"
  26547. BORDER="0"
  26548. CELLPADDING="0"
  26549. CELLSPACING="0"
  26550. CLASS="EXAMPLE"
  26551. ><TR
  26552. ><TD
  26553. ><DIV
  26554. CLASS="example"
  26555. ><A
  26556. NAME="AEN4769"
  26557. ></A
  26558. ><P
  26559. ><B
  26560. >Example 16-4. Basic <A
  26561. HREF="#function.require"
  26562. ><B
  26563. CLASS="function"
  26564. >require()</B
  26565. ></A
  26566. > examples</B
  26567. ></P
  26568. ><TABLE
  26569. BORDER="0"
  26570. BGCOLOR="#E0E0E0"
  26571. CELLPADDING="5"
  26572. ><TR
  26573. ><TD
  26574. ><PRE
  26575. CLASS="php"
  26576. ><?php
  26577.  
  26578. require 'prepend.php';
  26579.  
  26580. require $somefile;
  26581.  
  26582. require ('somefile.txt');
  26583.  
  26584. ?></PRE
  26585. ></TD
  26586. ></TR
  26587. ></TABLE
  26588. ></DIV
  26589. ></TD
  26590. ></TR
  26591. ></TABLE
  26592. >
  26593.    </P
  26594. ><P
  26595. >     See the <A
  26596. HREF="#function.include"
  26597. ><B
  26598. CLASS="function"
  26599. >include()</B
  26600. ></A
  26601. > documentation for more examples.
  26602.    </P
  26603. ><P
  26604. >     <DIV
  26605. CLASS="note"
  26606. ><BLOCKQUOTE
  26607. CLASS="note"
  26608. ><P
  26609. ><B
  26610. >Note: </B
  26611. >
  26612.       Prior to PHP 4.0.2, the following applies: <A
  26613. HREF="#function.require"
  26614. ><B
  26615. CLASS="function"
  26616. >require()</B
  26617. ></A
  26618. >
  26619.       will always attempt to read the target file, even if the line it's on
  26620.       never executes.  The conditional statement won't affect
  26621.       <A
  26622. HREF="#function.require"
  26623. ><B
  26624. CLASS="function"
  26625. >require()</B
  26626. ></A
  26627. >. However, if the line on which the
  26628.       <A
  26629. HREF="#function.require"
  26630. ><B
  26631. CLASS="function"
  26632. >require()</B
  26633. ></A
  26634. > occurs is not executed, neither will any of
  26635.       the code in the target file be executed.  Similarly, looping structures
  26636.       do not affect the behaviour of <A
  26637. HREF="#function.require"
  26638. ><B
  26639. CLASS="function"
  26640. >require()</B
  26641. ></A
  26642. >. Although
  26643.       the code contained in the target file is still subject to the loop, the
  26644.       <A
  26645. HREF="#function.require"
  26646. ><B
  26647. CLASS="function"
  26648. >require()</B
  26649. ></A
  26650. > itself happens only once.
  26651.      </P
  26652. ></BLOCKQUOTE
  26653. ></DIV
  26654. >
  26655.    </P
  26656. ><DIV
  26657. CLASS="note"
  26658. ><BLOCKQUOTE
  26659. CLASS="note"
  26660. ><P
  26661. ><B
  26662. >Note: </B
  26663. >Because this is a 
  26664. language construct and not a function, it cannot be called using 
  26665. <A
  26666. HREF="#functions.variable-functions"
  26667. >variable functions</A
  26668. ></P
  26669. ></BLOCKQUOTE
  26670. ></DIV
  26671. ><DIV
  26672. CLASS="warning"
  26673. ><P
  26674. ></P
  26675. ><TABLE
  26676. CLASS="warning"
  26677. BORDER="1"
  26678. WIDTH="100%"
  26679. ><TR
  26680. ><TD
  26681. ALIGN="CENTER"
  26682. ><B
  26683. >Warning</B
  26684. ></TD
  26685. ></TR
  26686. ><TR
  26687. ><TD
  26688. ALIGN="LEFT"
  26689. ><P
  26690. >Windows versions of PHP
  26691. prior to PHP 4.3.0 do not support accessing remote files via this function, even if
  26692. <A
  26693. HREF="#ini.allow-url-fopen"
  26694. >allow_url_fopen</A
  26695. > is enabled.
  26696. </P
  26697. ></TD
  26698. ></TR
  26699. ></TABLE
  26700. ></DIV
  26701. ><P
  26702. >     See also <A
  26703. HREF="#function.include"
  26704. ><B
  26705. CLASS="function"
  26706. >include()</B
  26707. ></A
  26708. >, <A
  26709. HREF="#function.require-once"
  26710. ><B
  26711. CLASS="function"
  26712. >require_once()</B
  26713. ></A
  26714. >,
  26715.     <A
  26716. HREF="#function.include-once"
  26717. ><B
  26718. CLASS="function"
  26719. >include_once()</B
  26720. ></A
  26721. >, <A
  26722. HREF="#function.eval"
  26723. ><B
  26724. CLASS="function"
  26725. >eval()</B
  26726. ></A
  26727. >, 
  26728.     <A
  26729. HREF="#function.file"
  26730. ><B
  26731. CLASS="function"
  26732. >file()</B
  26733. ></A
  26734. >, <A
  26735. HREF="#function.readfile"
  26736. ><B
  26737. CLASS="function"
  26738. >readfile()</B
  26739. ></A
  26740. >, 
  26741.     <A
  26742. HREF="#function.virtual"
  26743. ><B
  26744. CLASS="function"
  26745. >virtual()</B
  26746. ></A
  26747. > and <A
  26748. HREF="#ini.include-path"
  26749. >include_path</A
  26750. >.
  26751.    </P
  26752. ></DIV
  26753. ><DIV
  26754. CLASS="sect1"
  26755. ><HR><H2
  26756. CLASS="sect1"
  26757. ><A
  26758. NAME="function.include"
  26759. ><A
  26760. HREF="#function.include"
  26761. ><B
  26762. CLASS="function"
  26763. >include()</B
  26764. ></A
  26765. ></A
  26766. ></H2
  26767. ><P
  26768. >     The <A
  26769. HREF="#function.include"
  26770. ><B
  26771. CLASS="function"
  26772. >include()</B
  26773. ></A
  26774. > statement includes and evaluates
  26775.     the specified file.
  26776.    </P
  26777. ><P
  26778. >      The documentation below also applies to <A
  26779. HREF="#function.require"
  26780. ><B
  26781. CLASS="function"
  26782. >require()</B
  26783. ></A
  26784. >.
  26785.      The two constructs are identical in every way except how they handle
  26786.      failure.  <A
  26787. HREF="#function.include"
  26788. ><B
  26789. CLASS="function"
  26790. >include()</B
  26791. ></A
  26792. > produces a 
  26793.      <A
  26794. HREF="#internal.e-warning"
  26795. >Warning</A
  26796. > while <A
  26797. HREF="#function.require"
  26798. ><B
  26799. CLASS="function"
  26800. >require()</B
  26801. ></A
  26802. >
  26803.      results in a <A
  26804. HREF="#internal.e-error"
  26805. >Fatal Error</A
  26806. >.
  26807.      In other words, use <A
  26808. HREF="#function.require"
  26809. ><B
  26810. CLASS="function"
  26811. >require()</B
  26812. ></A
  26813. > if you want 
  26814.      a missing file to halt processing of the page.  <A
  26815. HREF="#function.include"
  26816. ><B
  26817. CLASS="function"
  26818. >include()</B
  26819. ></A
  26820. > does 
  26821.      not behave this way, the script will continue regardless.  Be sure to have an 
  26822.      appropriate <A
  26823. HREF="#ini.include-path"
  26824. >include_path</A
  26825. > setting as well.
  26826.      Be warned that parse error in required file doesn't cause processing halting.
  26827.    </P
  26828. ><P
  26829. >     Files for including are first looked in include_path relative to the current working directory
  26830.     and then in include_path relative to the directory of current script. E.g. if your include_path
  26831.     is <VAR
  26832. CLASS="literal"
  26833. >.</VAR
  26834. >, current working directory is <TT
  26835. CLASS="filename"
  26836. >/www/</TT
  26837. >,
  26838.     you included <TT
  26839. CLASS="filename"
  26840. >include/a.php</TT
  26841. > and there is <VAR
  26842. CLASS="literal"
  26843. >include "b.php"</VAR
  26844. >
  26845.     in that file, <TT
  26846. CLASS="filename"
  26847. >b.php</TT
  26848. > is first looked in <TT
  26849. CLASS="filename"
  26850. >/www/</TT
  26851. >
  26852.     and then in <TT
  26853. CLASS="filename"
  26854. >/www/include/</TT
  26855. >.
  26856.     If filename begins with <VAR
  26857. CLASS="literal"
  26858. >../</VAR
  26859. >, it is looked only in
  26860.     include_path relative to the current working directory.
  26861.    </P
  26862. ><P
  26863. >      When a file is included, the code it contains inherits the
  26864.      <A
  26865. HREF="#language.variables.scope"
  26866. >variable scope</A
  26867. > of the
  26868.      line on which the include occurs.  Any variables available at that line
  26869.      in the calling file will be available within the called file, from that
  26870.      point forward.
  26871.    </P
  26872. ><P
  26873. >      <TABLE
  26874. WIDTH="100%"
  26875. BORDER="0"
  26876. CELLPADDING="0"
  26877. CELLSPACING="0"
  26878. CLASS="EXAMPLE"
  26879. ><TR
  26880. ><TD
  26881. ><DIV
  26882. CLASS="example"
  26883. ><A
  26884. NAME="AEN4824"
  26885. ></A
  26886. ><P
  26887. ><B
  26888. >Example 16-5. Basic <A
  26889. HREF="#function.include"
  26890. ><B
  26891. CLASS="function"
  26892. >include()</B
  26893. ></A
  26894. > example</B
  26895. ></P
  26896. ><TABLE
  26897. BORDER="0"
  26898. BGCOLOR="#E0E0E0"
  26899. CELLPADDING="5"
  26900. ><TR
  26901. ><TD
  26902. ><PRE
  26903. CLASS="php"
  26904. >vars.php
  26905. <?php
  26906.  
  26907. $color = 'green';
  26908. $fruit = 'apple';
  26909.  
  26910. ?>
  26911.  
  26912. test.php
  26913. <?php
  26914.  
  26915. echo "A $color $fruit"; // A
  26916.  
  26917. include 'vars.php';
  26918.  
  26919. echo "A $color $fruit"; // A green apple
  26920.  
  26921. ?></PRE
  26922. ></TD
  26923. ></TR
  26924. ></TABLE
  26925. ></DIV
  26926. ></TD
  26927. ></TR
  26928. ></TABLE
  26929. >
  26930.    </P
  26931. ><P
  26932. >      If the include occurs inside a function within the calling file,
  26933.      then all of the code contained in the called file will behave as
  26934.      though it had been defined inside that function.  So, it will follow
  26935.      the variable scope of that function.
  26936.    </P
  26937. ><P
  26938. >      <TABLE
  26939. WIDTH="100%"
  26940. BORDER="0"
  26941. CELLPADDING="0"
  26942. CELLSPACING="0"
  26943. CLASS="EXAMPLE"
  26944. ><TR
  26945. ><TD
  26946. ><DIV
  26947. CLASS="example"
  26948. ><A
  26949. NAME="AEN4830"
  26950. ></A
  26951. ><P
  26952. ><B
  26953. >Example 16-6. Including within functions</B
  26954. ></P
  26955. ><TABLE
  26956. BORDER="0"
  26957. BGCOLOR="#E0E0E0"
  26958. CELLPADDING="5"
  26959. ><TR
  26960. ><TD
  26961. ><PRE
  26962. CLASS="php"
  26963. ><?php
  26964.  
  26965. function foo()
  26966. {
  26967.     global $color;
  26968.  
  26969.     include 'vars.php';
  26970.  
  26971.     echo "A $color $fruit";
  26972. }
  26973.  
  26974. /* vars.php is in the scope of foo() so     *
  26975.  * $fruit is NOT available outside of this  *
  26976.  * scope.  $color is because we declared it *
  26977.  * as global.                               */
  26978.  
  26979. foo();                    // A green apple
  26980. echo "A $color $fruit";   // A green
  26981.  
  26982. ?></PRE
  26983. ></TD
  26984. ></TR
  26985. ></TABLE
  26986. ></DIV
  26987. ></TD
  26988. ></TR
  26989. ></TABLE
  26990. >
  26991.    </P
  26992. ><P
  26993. >      When a file is included, parsing drops out of PHP mode and
  26994.      into HTML mode at the beginning of the target file, and resumes
  26995.      again at the end.  For this reason, any code inside the target
  26996.      file which should be executed as PHP code must be enclosed within
  26997.      <A
  26998. HREF="#language.basic-syntax.phpmode"
  26999. >valid PHP start
  27000.      and end tags</A
  27001. >.
  27002.    </P
  27003. ><P
  27004. >      If "<A
  27005. HREF="#ini.allow-url-fopen"
  27006. >URL fopen wrappers</A
  27007. >"
  27008.      are enabled in PHP (which they are in the default configuration),
  27009.      you can specify the file to be included using a URL (via HTTP or
  27010.      other supported wrapper - see <A
  27011. HREF="#wrappers"
  27012. >Appendix L</A
  27013. > for a list
  27014.      of protocols) instead of a local pathname.  If the target server interprets
  27015.      the target file as PHP code, variables may be passed to the included
  27016.      file using a URL request string as used with HTTP GET.  This is
  27017.      not strictly speaking the same thing as including the file and having
  27018.      it inherit the parent file's variable scope; the script is actually
  27019.      being run on the remote server and the result is then being
  27020.      included into the local script.
  27021.    </P
  27022. ><DIV
  27023. CLASS="warning"
  27024. ><P
  27025. ></P
  27026. ><TABLE
  27027. CLASS="warning"
  27028. BORDER="1"
  27029. WIDTH="100%"
  27030. ><TR
  27031. ><TD
  27032. ALIGN="CENTER"
  27033. ><B
  27034. >Warning</B
  27035. ></TD
  27036. ></TR
  27037. ><TR
  27038. ><TD
  27039. ALIGN="LEFT"
  27040. ><P
  27041. >Windows versions of PHP
  27042. prior to PHP 4.3.0 do not support accessing remote files via this function, even if
  27043. <A
  27044. HREF="#ini.allow-url-fopen"
  27045. >allow_url_fopen</A
  27046. > is enabled.
  27047. </P
  27048. ></TD
  27049. ></TR
  27050. ></TABLE
  27051. ></DIV
  27052. ><P
  27053. >     <TABLE
  27054. WIDTH="100%"
  27055. BORDER="0"
  27056. CELLPADDING="0"
  27057. CELLSPACING="0"
  27058. CLASS="EXAMPLE"
  27059. ><TR
  27060. ><TD
  27061. ><DIV
  27062. CLASS="example"
  27063. ><A
  27064. NAME="AEN4842"
  27065. ></A
  27066. ><P
  27067. ><B
  27068. >Example 16-7. <A
  27069. HREF="#function.include"
  27070. ><B
  27071. CLASS="function"
  27072. >include()</B
  27073. ></A
  27074. > through HTTP</B
  27075. ></P
  27076. ><TABLE
  27077. BORDER="0"
  27078. BGCOLOR="#E0E0E0"
  27079. CELLPADDING="5"
  27080. ><TR
  27081. ><TD
  27082. ><PRE
  27083. CLASS="php"
  27084. ><?php
  27085.  
  27086. /* This example assumes that www.example.com is configured to parse .php
  27087.  * files and not .txt files. Also, 'Works' here means that the variables
  27088.  * $foo and $bar are available within the included file. */
  27089.  
  27090. // Won't work; file.txt wasn't handled by www.example.com as PHP
  27091. include 'http://www.example.com/file.txt?foo=1&bar=2';
  27092.  
  27093. // Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
  27094. // local filesystem.
  27095. include 'file.php?foo=1&bar=2';
  27096.  
  27097. // Works.
  27098. include 'http://www.example.com/file.php?foo=1&bar=2';
  27099.  
  27100. $foo = 1;
  27101. $bar = 2;
  27102. include 'file.txt';  // Works.
  27103. include 'file.php';  // Works.
  27104.  
  27105. ?></PRE
  27106. ></TD
  27107. ></TR
  27108. ></TABLE
  27109. ></DIV
  27110. ></TD
  27111. ></TR
  27112. ></TABLE
  27113. >
  27114.     See also <A
  27115. HREF="#features.remote-files"
  27116. >Remote files</A
  27117. >,
  27118.     <A
  27119. HREF="#function.fopen"
  27120. ><B
  27121. CLASS="function"
  27122. >fopen()</B
  27123. ></A
  27124. > and <A
  27125. HREF="#function.file"
  27126. ><B
  27127. CLASS="function"
  27128. >file()</B
  27129. ></A
  27130. > for related 
  27131.     information.
  27132.    </P
  27133. ><P
  27134. >      Because <A
  27135. HREF="#function.include"
  27136. ><B
  27137. CLASS="function"
  27138. >include()</B
  27139. ></A
  27140. > and <A
  27141. HREF="#function.require"
  27142. ><B
  27143. CLASS="function"
  27144. >require()</B
  27145. ></A
  27146. >
  27147.      are special language constructs, you must enclose them within a statement
  27148.      block if it's inside a conditional block.
  27149.    </P
  27150. ><P
  27151. >     <TABLE
  27152. WIDTH="100%"
  27153. BORDER="0"
  27154. CELLPADDING="0"
  27155. CELLSPACING="0"
  27156. CLASS="EXAMPLE"
  27157. ><TR
  27158. ><TD
  27159. ><DIV
  27160. CLASS="example"
  27161. ><A
  27162. NAME="AEN4853"
  27163. ></A
  27164. ><P
  27165. ><B
  27166. >Example 16-8. include() and conditional blocks</B
  27167. ></P
  27168. ><TABLE
  27169. BORDER="0"
  27170. BGCOLOR="#E0E0E0"
  27171. CELLPADDING="5"
  27172. ><TR
  27173. ><TD
  27174. ><PRE
  27175. CLASS="php"
  27176. ><?php
  27177.  
  27178. // This is WRONG and will not work as desired.
  27179. if ($condition)
  27180.     include $file;
  27181. else
  27182.     include $other;
  27183.  
  27184.  
  27185. // This is CORRECT.
  27186. if ($condition) {
  27187.     include $file;
  27188. } else {
  27189.     include $other;
  27190. }
  27191.  
  27192. ?></PRE
  27193. ></TD
  27194. ></TR
  27195. ></TABLE
  27196. ></DIV
  27197. ></TD
  27198. ></TR
  27199. ></TABLE
  27200. >
  27201.    </P
  27202. ><P
  27203. >     Handling Returns: It is possible to execute a <A
  27204. HREF="#function.return"
  27205. ><B
  27206. CLASS="function"
  27207. >return()</B
  27208. ></A
  27209. >
  27210.     statement inside an included file in order to terminate processing in that
  27211.     file and return to the script which called it.  Also, it's possible to return
  27212.     values from included files.  You can take the value of the include call as
  27213.     you would a normal function.  This is not, however, possible when including
  27214.     remote files unless the output of the remote file has
  27215.     <A
  27216. HREF="#language.basic-syntax.phpmode"
  27217. >valid PHP start
  27218.     and end tags</A
  27219. > (as with any local file).  You can declare the needed
  27220.     variables within those tags and they will be introduced at whichever point
  27221.     the file was included.
  27222.    </P
  27223. ><P
  27224. >     Because <A
  27225. HREF="#function.include"
  27226. ><B
  27227. CLASS="function"
  27228. >include()</B
  27229. ></A
  27230. > is a special language construct,
  27231.     parentheses are not needed around its argument. Take care when comparing
  27232.     return value.
  27233.     <TABLE
  27234. WIDTH="100%"
  27235. BORDER="0"
  27236. CELLPADDING="0"
  27237. CELLSPACING="0"
  27238. CLASS="EXAMPLE"
  27239. ><TR
  27240. ><TD
  27241. ><DIV
  27242. CLASS="example"
  27243. ><A
  27244. NAME="AEN4861"
  27245. ></A
  27246. ><P
  27247. ><B
  27248. >Example 16-9. Comparing return value of include</B
  27249. ></P
  27250. ><TABLE
  27251. BORDER="0"
  27252. BGCOLOR="#E0E0E0"
  27253. CELLPADDING="5"
  27254. ><TR
  27255. ><TD
  27256. ><PRE
  27257. CLASS="php"
  27258. ><?php
  27259. // won't work, evaluated as include(('vars.php') == 'OK'), i.e. include('')
  27260. if (include('vars.php') == 'OK') {
  27261.     echo 'OK';
  27262. }
  27263.  
  27264. // works
  27265. if ((include 'vars.php') == 'OK') {
  27266.     echo 'OK';
  27267. }
  27268. ?></PRE
  27269. ></TD
  27270. ></TR
  27271. ></TABLE
  27272. ></DIV
  27273. ></TD
  27274. ></TR
  27275. ></TABLE
  27276. >
  27277.    </P
  27278. ><P
  27279. >     <DIV
  27280. CLASS="note"
  27281. ><BLOCKQUOTE
  27282. CLASS="note"
  27283. ><P
  27284. ><B
  27285. >Note: </B
  27286. >
  27287.       In PHP 3, the return may not appear inside a block unless it's
  27288.       a function block, in which case the <A
  27289. HREF="#function.return"
  27290. ><B
  27291. CLASS="function"
  27292. >return()</B
  27293. ></A
  27294. > applies 
  27295.       to that function and not the whole file.
  27296.      </P
  27297. ></BLOCKQUOTE
  27298. ></DIV
  27299. >
  27300.    </P
  27301. ><P
  27302. >     <TABLE
  27303. WIDTH="100%"
  27304. BORDER="0"
  27305. CELLPADDING="0"
  27306. CELLSPACING="0"
  27307. CLASS="EXAMPLE"
  27308. ><TR
  27309. ><TD
  27310. ><DIV
  27311. CLASS="example"
  27312. ><A
  27313. NAME="AEN4869"
  27314. ></A
  27315. ><P
  27316. ><B
  27317. >Example 16-10. <A
  27318. HREF="#function.include"
  27319. ><B
  27320. CLASS="function"
  27321. >include()</B
  27322. ></A
  27323. > and the <A
  27324. HREF="#function.return"
  27325. ><B
  27326. CLASS="function"
  27327. >return()</B
  27328. ></A
  27329. > statement</B
  27330. ></P
  27331. ><TABLE
  27332. BORDER="0"
  27333. BGCOLOR="#E0E0E0"
  27334. CELLPADDING="5"
  27335. ><TR
  27336. ><TD
  27337. ><PRE
  27338. CLASS="php"
  27339. >return.php
  27340. <?php
  27341.  
  27342. $var = 'PHP';
  27343.  
  27344. return $var;
  27345.  
  27346. ?>
  27347.  
  27348. noreturn.php
  27349. <?php
  27350.  
  27351. $var = 'PHP';
  27352.  
  27353. ?>
  27354.  
  27355. testreturns.php
  27356. <?php
  27357.  
  27358. $foo = include 'return.php';
  27359.  
  27360. echo $foo; // prints 'PHP'
  27361.  
  27362. $bar = include 'noreturn.php';
  27363.  
  27364. echo $bar; // prints 1
  27365.  
  27366. ?></PRE
  27367. ></TD
  27368. ></TR
  27369. ></TABLE
  27370. ></DIV
  27371. ></TD
  27372. ></TR
  27373. ></TABLE
  27374. >
  27375.    </P
  27376. ><P
  27377. >     <VAR
  27378. CLASS="literal"
  27379. >$bar</VAR
  27380. > is the value <VAR
  27381. CLASS="literal"
  27382. >1</VAR
  27383. > because the include 
  27384.     was successful.  Notice the difference between the above examples.  The first uses 
  27385.     <A
  27386. HREF="#function.return"
  27387. ><B
  27388. CLASS="function"
  27389. >return()</B
  27390. ></A
  27391. > within the included file while the other does not.  
  27392.     If the file can't be included, <TT
  27393. CLASS="constant"
  27394. ><B
  27395. >FALSE</B
  27396. ></TT
  27397. > is returned and
  27398.     <VAR
  27399. CLASS="literal"
  27400. >E_WARNING</VAR
  27401. > is issued.
  27402.    </P
  27403. ><P
  27404. >     If there are functions defined in the included file, they can be used in the
  27405.     main file independent if they are before <A
  27406. HREF="#function.return"
  27407. ><B
  27408. CLASS="function"
  27409. >return()</B
  27410. ></A
  27411. > or after.
  27412.     If the file is included twice, PHP 5 issues fatal error because functions
  27413.     were already declared, while PHP 4 doesn't complain about functions
  27414.     defined after <A
  27415. HREF="#function.return"
  27416. ><B
  27417. CLASS="function"
  27418. >return()</B
  27419. ></A
  27420. >.
  27421.     It is recommended to use <A
  27422. HREF="#function.include-once"
  27423. ><B
  27424. CLASS="function"
  27425. >include_once()</B
  27426. ></A
  27427. > instead of
  27428.     checking if the file was already included and conditionally return inside
  27429.     the included file.
  27430.    </P
  27431. ><P
  27432. >     A few other ways to "include" files into variables are with 
  27433.     <A
  27434. HREF="#function.fopen"
  27435. ><B
  27436. CLASS="function"
  27437. >fopen()</B
  27438. ></A
  27439. >, <A
  27440. HREF="#function.file"
  27441. ><B
  27442. CLASS="function"
  27443. >file()</B
  27444. ></A
  27445. > or by using 
  27446.     <A
  27447. HREF="#function.include"
  27448. ><B
  27449. CLASS="function"
  27450. >include()</B
  27451. ></A
  27452. > along with 
  27453.     <A
  27454. HREF="#ref.outcontrol"
  27455. >Output Control Functions</A
  27456. >.
  27457.    </P
  27458. ><DIV
  27459. CLASS="note"
  27460. ><BLOCKQUOTE
  27461. CLASS="note"
  27462. ><P
  27463. ><B
  27464. >Note: </B
  27465. >Because this is a 
  27466. language construct and not a function, it cannot be called using 
  27467. <A
  27468. HREF="#functions.variable-functions"
  27469. >variable functions</A
  27470. ></P
  27471. ></BLOCKQUOTE
  27472. ></DIV
  27473. ><P
  27474. >     See also <A
  27475. HREF="#function.require"
  27476. ><B
  27477. CLASS="function"
  27478. >require()</B
  27479. ></A
  27480. >, <A
  27481. HREF="#function.require-once"
  27482. ><B
  27483. CLASS="function"
  27484. >require_once()</B
  27485. ></A
  27486. >,
  27487.     <A
  27488. HREF="#function.include-once"
  27489. ><B
  27490. CLASS="function"
  27491. >include_once()</B
  27492. ></A
  27493. >, <A
  27494. HREF="#function.readfile"
  27495. ><B
  27496. CLASS="function"
  27497. >readfile()</B
  27498. ></A
  27499. >,
  27500.     <A
  27501. HREF="#function.virtual"
  27502. ><B
  27503. CLASS="function"
  27504. >virtual()</B
  27505. ></A
  27506. >, and
  27507.     <A
  27508. HREF="#ini.include-path"
  27509. >include_path</A
  27510. >.
  27511.    </P
  27512. ></DIV
  27513. ><DIV
  27514. CLASS="sect1"
  27515. ><HR><H2
  27516. CLASS="sect1"
  27517. ><A
  27518. NAME="function.require-once"
  27519. ><A
  27520. HREF="#function.require-once"
  27521. ><B
  27522. CLASS="function"
  27523. >require_once()</B
  27524. ></A
  27525. ></A
  27526. ></H2
  27527. ><P
  27528. >     The <A
  27529. HREF="#function.require-once"
  27530. ><B
  27531. CLASS="function"
  27532. >require_once()</B
  27533. ></A
  27534. > statement includes and evaluates
  27535.     the specified file during the execution of the script.
  27536.     This is a behavior similar to the <A
  27537. HREF="#function.require"
  27538. ><B
  27539. CLASS="function"
  27540. >require()</B
  27541. ></A
  27542. > statement,
  27543.     with the only difference being that if the code from a file has already
  27544.     been included, it will not be included again.  See the documentation for
  27545.     <A
  27546. HREF="#function.require"
  27547. ><B
  27548. CLASS="function"
  27549. >require()</B
  27550. ></A
  27551. > for more information on how this statement 
  27552.     works.
  27553.    </P
  27554. ><P
  27555. >     <A
  27556. HREF="#function.require-once"
  27557. ><B
  27558. CLASS="function"
  27559. >require_once()</B
  27560. ></A
  27561. > should be used in cases where
  27562.     the same file might be included and evaluated more than once during a
  27563.     particular execution of a script, and you want to be sure that it is
  27564.     included exactly once to avoid problems with function redefinitions,
  27565.     variable value reassignments, etc.
  27566.    </P
  27567. ><P
  27568. >      For examples on using <A
  27569. HREF="#function.require-once"
  27570. ><B
  27571. CLASS="function"
  27572. >require_once()</B
  27573. ></A
  27574. > and
  27575.      <A
  27576. HREF="#function.include-once"
  27577. ><B
  27578. CLASS="function"
  27579. >include_once()</B
  27580. ></A
  27581. >, look at the 
  27582.      <A
  27583. HREF="http://pear.php.net/"
  27584. TARGET="_top"
  27585. >PEAR</A
  27586. > code included in the 
  27587.      latest PHP source code distributions.
  27588.    </P
  27589. ><P
  27590. >     Return values are the same as with <A
  27591. HREF="#function.include"
  27592. ><B
  27593. CLASS="function"
  27594. >include()</B
  27595. ></A
  27596. >. If the file
  27597.     was already included, this function returns <TT
  27598. CLASS="constant"
  27599. ><B
  27600. >TRUE</B
  27601. ></TT
  27602. >
  27603.    </P
  27604. ><P
  27605. >     <DIV
  27606. CLASS="note"
  27607. ><BLOCKQUOTE
  27608. CLASS="note"
  27609. ><P
  27610. ><B
  27611. >Note: </B
  27612. >
  27613.       <A
  27614. HREF="#function.require-once"
  27615. ><B
  27616. CLASS="function"
  27617. >require_once()</B
  27618. ></A
  27619. > was added in PHP 4.0.1pl2
  27620.      </P
  27621. ></BLOCKQUOTE
  27622. ></DIV
  27623. >
  27624.    </P
  27625. ><P
  27626. >     <DIV
  27627. CLASS="note"
  27628. ><BLOCKQUOTE
  27629. CLASS="note"
  27630. ><P
  27631. ><B
  27632. >Note: </B
  27633. >
  27634.       Be aware, that the behaviour of <A
  27635. HREF="#function.require-once"
  27636. ><B
  27637. CLASS="function"
  27638. >require_once()</B
  27639. ></A
  27640. >
  27641.       and <A
  27642. HREF="#function.include-once"
  27643. ><B
  27644. CLASS="function"
  27645. >include_once()</B
  27646. ></A
  27647. > may not be what you expect
  27648.       on a non case sensitive operating system (such as Windows).
  27649.       <TABLE
  27650. WIDTH="100%"
  27651. BORDER="0"
  27652. CELLPADDING="0"
  27653. CELLSPACING="0"
  27654. CLASS="EXAMPLE"
  27655. ><TR
  27656. ><TD
  27657. ><DIV
  27658. CLASS="example"
  27659. ><A
  27660. NAME="AEN4924"
  27661. ></A
  27662. ><P
  27663. ><B
  27664. >Example 16-11. <A
  27665. HREF="#function.require-once"
  27666. ><B
  27667. CLASS="function"
  27668. >require_once()</B
  27669. ></A
  27670. > is case insensitive on Windows</B
  27671. ></P
  27672. ><TABLE
  27673. BORDER="0"
  27674. BGCOLOR="#E0E0E0"
  27675. CELLPADDING="5"
  27676. ><TR
  27677. ><TD
  27678. ><PRE
  27679. CLASS="php"
  27680. ><?php
  27681. require_once("a.php"); // this will include a.php
  27682. require_once("A.php"); // this will include a.php again on Windows! (PHP 4 only)
  27683. ?></PRE
  27684. ></TD
  27685. ></TR
  27686. ></TABLE
  27687. ></DIV
  27688. ></TD
  27689. ></TR
  27690. ></TABLE
  27691. >
  27692.       This behaviour changed in PHP 5 - the path is normalized first so that
  27693.       <TT
  27694. CLASS="filename"
  27695. >C:\PROGRA~1\A.php</TT
  27696. > is realized the same as
  27697.       <TT
  27698. CLASS="filename"
  27699. >C:\Program Files\a.php</TT
  27700. > and the file is required just once.
  27701.      </P
  27702. ></BLOCKQUOTE
  27703. ></DIV
  27704. >
  27705.    </P
  27706. ><DIV
  27707. CLASS="warning"
  27708. ><P
  27709. ></P
  27710. ><TABLE
  27711. CLASS="warning"
  27712. BORDER="1"
  27713. WIDTH="100%"
  27714. ><TR
  27715. ><TD
  27716. ALIGN="CENTER"
  27717. ><B
  27718. >Warning</B
  27719. ></TD
  27720. ></TR
  27721. ><TR
  27722. ><TD
  27723. ALIGN="LEFT"
  27724. ><P
  27725. >Windows versions of PHP
  27726. prior to PHP 4.3.0 do not support accessing remote files via this function, even if
  27727. <A
  27728. HREF="#ini.allow-url-fopen"
  27729. >allow_url_fopen</A
  27730. > is enabled.
  27731. </P
  27732. ></TD
  27733. ></TR
  27734. ></TABLE
  27735. ></DIV
  27736. ><P
  27737. >     See also <A
  27738. HREF="#function.require"
  27739. ><B
  27740. CLASS="function"
  27741. >require()</B
  27742. ></A
  27743. >,
  27744.     <A
  27745. HREF="#function.include"
  27746. ><B
  27747. CLASS="function"
  27748. >include()</B
  27749. ></A
  27750. >, <A
  27751. HREF="#function.include-once"
  27752. ><B
  27753. CLASS="function"
  27754. >include_once()</B
  27755. ></A
  27756. >,
  27757.     <A
  27758. HREF="#function.get-required-files"
  27759. ><B
  27760. CLASS="function"
  27761. >get_required_files()</B
  27762. ></A
  27763. >,
  27764.     <A
  27765. HREF="#function.get-included-files"
  27766. ><B
  27767. CLASS="function"
  27768. >get_included_files()</B
  27769. ></A
  27770. >, <A
  27771. HREF="#function.readfile"
  27772. ><B
  27773. CLASS="function"
  27774. >readfile()</B
  27775. ></A
  27776. >, and 
  27777.     <A
  27778. HREF="#function.virtual"
  27779. ><B
  27780. CLASS="function"
  27781. >virtual()</B
  27782. ></A
  27783. >.
  27784.    </P
  27785. ></DIV
  27786. ><DIV
  27787. CLASS="sect1"
  27788. ><HR><H2
  27789. CLASS="sect1"
  27790. ><A
  27791. NAME="function.include-once"
  27792. ><A
  27793. HREF="#function.include-once"
  27794. ><B
  27795. CLASS="function"
  27796. >include_once()</B
  27797. ></A
  27798. ></A
  27799. ></H2
  27800. ><P
  27801. >     The <A
  27802. HREF="#function.include-once"
  27803. ><B
  27804. CLASS="function"
  27805. >include_once()</B
  27806. ></A
  27807. > statement includes and evaluates
  27808.     the specified file during the execution of the script.
  27809.     This is a behavior similar to the <A
  27810. HREF="#function.include"
  27811. ><B
  27812. CLASS="function"
  27813. >include()</B
  27814. ></A
  27815. > statement,
  27816.     with the only difference being that if the code from a file has already
  27817.     been included, it will not be included again.  As the name suggests, 
  27818.     it will be included just once.
  27819.    </P
  27820. ><P
  27821. >     <A
  27822. HREF="#function.include-once"
  27823. ><B
  27824. CLASS="function"
  27825. >include_once()</B
  27826. ></A
  27827. > should be used in cases where 
  27828.     the same file might be included and evaluated more than once during a
  27829.     particular execution of a script, and you want to be sure that it is
  27830.     included exactly once to avoid problems with function redefinitions,
  27831.     variable value reassignments, etc.
  27832.    </P
  27833. ><P
  27834. >     For more examples on using <A
  27835. HREF="#function.require-once"
  27836. ><B
  27837. CLASS="function"
  27838. >require_once()</B
  27839. ></A
  27840. > and
  27841.     <A
  27842. HREF="#function.include-once"
  27843. ><B
  27844. CLASS="function"
  27845. >include_once()</B
  27846. ></A
  27847. >, look at the
  27848.     <A
  27849. HREF="http://pear.php.net/"
  27850. TARGET="_top"
  27851. >PEAR</A
  27852. > code included in the latest
  27853.     PHP source code distributions.
  27854.    </P
  27855. ><P
  27856. >     Return values are the same as with <A
  27857. HREF="#function.include"
  27858. ><B
  27859. CLASS="function"
  27860. >include()</B
  27861. ></A
  27862. >. If the file
  27863.     was already included, this function returns <TT
  27864. CLASS="constant"
  27865. ><B
  27866. >TRUE</B
  27867. ></TT
  27868. >
  27869.    </P
  27870. ><P
  27871. >     <DIV
  27872. CLASS="note"
  27873. ><BLOCKQUOTE
  27874. CLASS="note"
  27875. ><P
  27876. ><B
  27877. >Note: </B
  27878. >
  27879.       <A
  27880. HREF="#function.include-once"
  27881. ><B
  27882. CLASS="function"
  27883. >include_once()</B
  27884. ></A
  27885. > was added in PHP 4.0.1pl2
  27886.      </P
  27887. ></BLOCKQUOTE
  27888. ></DIV
  27889. >
  27890.    </P
  27891. ><P
  27892. >    <DIV
  27893. CLASS="note"
  27894. ><BLOCKQUOTE
  27895. CLASS="note"
  27896. ><P
  27897. ><B
  27898. >Note: </B
  27899. >
  27900.       Be aware, that the behaviour of <A
  27901. HREF="#function.include-once"
  27902. ><B
  27903. CLASS="function"
  27904. >include_once()</B
  27905. ></A
  27906. >
  27907.       and <A
  27908. HREF="#function.require-once"
  27909. ><B
  27910. CLASS="function"
  27911. >require_once()</B
  27912. ></A
  27913. > may not be what you expect
  27914.       on a non case sensitive operating system (such as Windows).
  27915.       <TABLE
  27916. WIDTH="100%"
  27917. BORDER="0"
  27918. CELLPADDING="0"
  27919. CELLSPACING="0"
  27920. CLASS="EXAMPLE"
  27921. ><TR
  27922. ><TD
  27923. ><DIV
  27924. CLASS="example"
  27925. ><A
  27926. NAME="AEN4965"
  27927. ></A
  27928. ><P
  27929. ><B
  27930. >Example 16-12. <A
  27931. HREF="#function.include-once"
  27932. ><B
  27933. CLASS="function"
  27934. >include_once()</B
  27935. ></A
  27936. > is case insensitive on Windows</B
  27937. ></P
  27938. ><TABLE
  27939. BORDER="0"
  27940. BGCOLOR="#E0E0E0"
  27941. CELLPADDING="5"
  27942. ><TR
  27943. ><TD
  27944. ><PRE
  27945. CLASS="php"
  27946. ><?php
  27947. include_once("a.php"); // this will include a.php
  27948. include_once("A.php"); // this will include a.php again on Windows! (PHP 4 only)
  27949. ?></PRE
  27950. ></TD
  27951. ></TR
  27952. ></TABLE
  27953. ></DIV
  27954. ></TD
  27955. ></TR
  27956. ></TABLE
  27957. >
  27958.       This behaviour changed in PHP 5 - the path is normalized first so that
  27959.       <TT
  27960. CLASS="filename"
  27961. >C:\PROGRA~1\A.php</TT
  27962. > is realized the same as
  27963.       <TT
  27964. CLASS="filename"
  27965. >C:\Program Files\a.php</TT
  27966. > and the file is included just once.
  27967.      </P
  27968. ></BLOCKQUOTE
  27969. ></DIV
  27970. >
  27971.    </P
  27972. ><DIV
  27973. CLASS="warning"
  27974. ><P
  27975. ></P
  27976. ><TABLE
  27977. CLASS="warning"
  27978. BORDER="1"
  27979. WIDTH="100%"
  27980. ><TR
  27981. ><TD
  27982. ALIGN="CENTER"
  27983. ><B
  27984. >Warning</B
  27985. ></TD
  27986. ></TR
  27987. ><TR
  27988. ><TD
  27989. ALIGN="LEFT"
  27990. ><P
  27991. >Windows versions of PHP
  27992. prior to PHP 4.3.0 do not support accessing remote files via this function, even if
  27993. <A
  27994. HREF="#ini.allow-url-fopen"
  27995. >allow_url_fopen</A
  27996. > is enabled.
  27997. </P
  27998. ></TD
  27999. ></TR
  28000. ></TABLE
  28001. ></DIV
  28002. ><P
  28003. >     See also <A
  28004. HREF="#function.include"
  28005. ><B
  28006. CLASS="function"
  28007. >include()</B
  28008. ></A
  28009. >,
  28010.     <A
  28011. HREF="#function.require"
  28012. ><B
  28013. CLASS="function"
  28014. >require()</B
  28015. ></A
  28016. >, <A
  28017. HREF="#function.require-once"
  28018. ><B
  28019. CLASS="function"
  28020. >require_once()</B
  28021. ></A
  28022. >,
  28023.     <A
  28024. HREF="#function.get-required-files"
  28025. ><B
  28026. CLASS="function"
  28027. >get_required_files()</B
  28028. ></A
  28029. >,
  28030.     <A
  28031. HREF="#function.get-included-files"
  28032. ><B
  28033. CLASS="function"
  28034. >get_included_files()</B
  28035. ></A
  28036. >, <A
  28037. HREF="#function.readfile"
  28038. ><B
  28039. CLASS="function"
  28040. >readfile()</B
  28041. ></A
  28042. >,
  28043.     and <A
  28044. HREF="#function.virtual"
  28045. ><B
  28046. CLASS="function"
  28047. >virtual()</B
  28048. ></A
  28049. >.
  28050.    </P
  28051. ></DIV
  28052. ></DIV
  28053. ><DIV
  28054. CLASS="chapter"
  28055. ><HR><H1
  28056. ><A
  28057. NAME="language.functions"
  28058. >Chapter 17. Functions</A
  28059. ></H1
  28060. ><DIV
  28061. CLASS="sect1"
  28062. ><H2
  28063. CLASS="sect1"
  28064. ><A
  28065. NAME="functions.user-defined"
  28066. >User-defined functions</A
  28067. ></H2
  28068. ><P
  28069. >     A function may be defined using syntax such as the following:
  28070.    </P
  28071. ><P
  28072. >     <TABLE
  28073. WIDTH="100%"
  28074. BORDER="0"
  28075. CELLPADDING="0"
  28076. CELLSPACING="0"
  28077. CLASS="EXAMPLE"
  28078. ><TR
  28079. ><TD
  28080. ><DIV
  28081. CLASS="example"
  28082. ><A
  28083. NAME="AEN4988"
  28084. ></A
  28085. ><P
  28086. ><B
  28087. >Example 17-1. Pseudo code to demonstrate function uses</B
  28088. ></P
  28089. ><TABLE
  28090. BORDER="0"
  28091. BGCOLOR="#E0E0E0"
  28092. CELLPADDING="5"
  28093. ><TR
  28094. ><TD
  28095. ><PRE
  28096. CLASS="php"
  28097. ><?php
  28098. function foo($arg_1, $arg_2, /* ..., */ $arg_n)
  28099. {
  28100.     echo "Example function.\n";
  28101.     return $retval;
  28102. }
  28103. ?></PRE
  28104. ></TD
  28105. ></TR
  28106. ></TABLE
  28107. ></DIV
  28108. ></TD
  28109. ></TR
  28110. ></TABLE
  28111. >
  28112.    </P
  28113. ><P
  28114. >     Any valid PHP code may appear inside a function, even other
  28115.     functions and <A
  28116. HREF="#keyword.class"
  28117. >class</A
  28118. >
  28119.     definitions.
  28120.    </P
  28121. ><P
  28122. >     In PHP 3, functions must be defined before they are referenced. No
  28123.     such requirement exists since PHP 4. <SPAN
  28124. CLASS="emphasis"
  28125. ><I
  28126. CLASS="emphasis"
  28127. >Except</I
  28128. ></SPAN
  28129. > when
  28130.     a function is conditionally defined such as shown in the two examples
  28131.     below.
  28132.    </P
  28133. ><P
  28134. >     When a function is defined in a conditional manner such as the two
  28135.     examples shown.  Its definition must be processed <SPAN
  28136. CLASS="emphasis"
  28137. ><I
  28138. CLASS="emphasis"
  28139. >prior</I
  28140. ></SPAN
  28141. >
  28142.     to being called.
  28143.    </P
  28144. ><P
  28145. >     <TABLE
  28146. WIDTH="100%"
  28147. BORDER="0"
  28148. CELLPADDING="0"
  28149. CELLSPACING="0"
  28150. CLASS="EXAMPLE"
  28151. ><TR
  28152. ><TD
  28153. ><DIV
  28154. CLASS="example"
  28155. ><A
  28156. NAME="AEN4998"
  28157. ></A
  28158. ><P
  28159. ><B
  28160. >Example 17-2. Conditional functions</B
  28161. ></P
  28162. ><TABLE
  28163. BORDER="0"
  28164. BGCOLOR="#E0E0E0"
  28165. CELLPADDING="5"
  28166. ><TR
  28167. ><TD
  28168. ><PRE
  28169. CLASS="php"
  28170. ><?php
  28171.  
  28172. $makefoo = true;
  28173.  
  28174. /* We can't call foo() from here 
  28175.    since it doesn't exist yet,
  28176.    but we can call bar() */
  28177.  
  28178. bar();
  28179.  
  28180. if ($makefoo) {
  28181.   function foo()
  28182.   {
  28183.     echo "I don't exist until program execution reaches me.\n";
  28184.   }
  28185. }
  28186.  
  28187. /* Now we can safely call foo()
  28188.    since $makefoo evaluated to true */
  28189.  
  28190. if ($makefoo) foo();
  28191.  
  28192. function bar() 
  28193. {
  28194.   echo "I exist immediately upon program start.\n";
  28195. }
  28196.  
  28197. ?></PRE
  28198. ></TD
  28199. ></TR
  28200. ></TABLE
  28201. ></DIV
  28202. ></TD
  28203. ></TR
  28204. ></TABLE
  28205. >
  28206.    </P
  28207. ><P
  28208. >     <TABLE
  28209. WIDTH="100%"
  28210. BORDER="0"
  28211. CELLPADDING="0"
  28212. CELLSPACING="0"
  28213. CLASS="EXAMPLE"
  28214. ><TR
  28215. ><TD
  28216. ><DIV
  28217. CLASS="example"
  28218. ><A
  28219. NAME="AEN5002"
  28220. ></A
  28221. ><P
  28222. ><B
  28223. >Example 17-3. Functions within functions</B
  28224. ></P
  28225. ><TABLE
  28226. BORDER="0"
  28227. BGCOLOR="#E0E0E0"
  28228. CELLPADDING="5"
  28229. ><TR
  28230. ><TD
  28231. ><PRE
  28232. CLASS="php"
  28233. ><?php
  28234. function foo() 
  28235. {
  28236.   function bar() 
  28237.   {
  28238.     echo "I don't exist until foo() is called.\n";
  28239.   }
  28240. }
  28241.  
  28242. /* We can't call bar() yet
  28243.    since it doesn't exist. */
  28244.  
  28245. foo();
  28246.  
  28247. /* Now we can call bar(),
  28248.    foo()'s processesing has
  28249.    made it accessible. */
  28250.  
  28251. bar();
  28252.  
  28253. ?></PRE
  28254. ></TD
  28255. ></TR
  28256. ></TABLE
  28257. ></DIV
  28258. ></TD
  28259. ></TR
  28260. ></TABLE
  28261. >
  28262.    </P
  28263. ><P
  28264. >     PHP does not support function overloading, nor is it possible to
  28265.     undefine or redefine previously-declared functions.
  28266.    </P
  28267. ><DIV
  28268. CLASS="note"
  28269. ><BLOCKQUOTE
  28270. CLASS="note"
  28271. ><P
  28272. ><B
  28273. >Note: </B
  28274. >
  28275.      Function names are case-insensitive, though it is usually good form
  28276.      to call functions as they appear in their declaration.
  28277.     </P
  28278. ></BLOCKQUOTE
  28279. ></DIV
  28280. ><P
  28281. >     PHP 3 does not support variable numbers of arguments to functions,
  28282.     although default arguments are supported (see <A
  28283. HREF="#functions.arguments.default"
  28284. >Default argument
  28285.     values</A
  28286. > for more information). Both are supported, as of PHP 4: see <A
  28287. HREF="#functions.variable-arg-list"
  28288. >Variable-length argument
  28289.     lists</A
  28290. > and the function references for
  28291.     <A
  28292. HREF="#function.func-num-args"
  28293. ><B
  28294. CLASS="function"
  28295. >func_num_args()</B
  28296. ></A
  28297. >,
  28298.     <A
  28299. HREF="#function.func-get-arg"
  28300. ><B
  28301. CLASS="function"
  28302. >func_get_arg()</B
  28303. ></A
  28304. >, and
  28305.     <A
  28306. HREF="#function.func-get-args"
  28307. ><B
  28308. CLASS="function"
  28309. >func_get_args()</B
  28310. ></A
  28311. > for more information.
  28312.    </P
  28313. ></DIV
  28314. ><DIV
  28315. CLASS="sect1"
  28316. ><HR><H2
  28317. CLASS="sect1"
  28318. ><A
  28319. NAME="functions.arguments"
  28320. >Function arguments</A
  28321. ></H2
  28322. ><P
  28323. >     Information may be passed to functions via the argument list,
  28324.     which is a comma-delimited list of expressions.
  28325.    </P
  28326. ><P
  28327. >     PHP supports passing arguments by value (the default), <A
  28328. HREF="#functions.arguments.by-reference"
  28329. >passing by
  28330.     reference</A
  28331. >, and <A
  28332. HREF="#functions.arguments.default"
  28333. >default argument
  28334.     values</A
  28335. >. Variable-length argument lists are supported only
  28336.     in PHP 4 and later; see <A
  28337. HREF="#functions.variable-arg-list"
  28338. >Variable-length argument
  28339.     lists</A
  28340. > and the function references for
  28341.     <A
  28342. HREF="#function.func-num-args"
  28343. ><B
  28344. CLASS="function"
  28345. >func_num_args()</B
  28346. ></A
  28347. >,
  28348.     <A
  28349. HREF="#function.func-get-arg"
  28350. ><B
  28351. CLASS="function"
  28352. >func_get_arg()</B
  28353. ></A
  28354. >, and
  28355.     <A
  28356. HREF="#function.func-get-args"
  28357. ><B
  28358. CLASS="function"
  28359. >func_get_args()</B
  28360. ></A
  28361. > for more information. A
  28362.     similar effect can be achieved in PHP 3 by passing an array of
  28363.     arguments to a function:
  28364.    </P
  28365. ><P
  28366. >     <TABLE
  28367. WIDTH="100%"
  28368. BORDER="0"
  28369. CELLPADDING="0"
  28370. CELLSPACING="0"
  28371. CLASS="EXAMPLE"
  28372. ><TR
  28373. ><TD
  28374. ><DIV
  28375. CLASS="example"
  28376. ><A
  28377. NAME="AEN5025"
  28378. ></A
  28379. ><P
  28380. ><B
  28381. >Example 17-4. Passing arrays to functions</B
  28382. ></P
  28383. ><TABLE
  28384. BORDER="0"
  28385. BGCOLOR="#E0E0E0"
  28386. CELLPADDING="5"
  28387. ><TR
  28388. ><TD
  28389. ><PRE
  28390. CLASS="php"
  28391. ><?php
  28392. function takes_array($input)
  28393. {
  28394.     echo "$input[0] + $input[1] = ", $input[0]+$input[1];
  28395. }
  28396. ?></PRE
  28397. ></TD
  28398. ></TR
  28399. ></TABLE
  28400. ></DIV
  28401. ></TD
  28402. ></TR
  28403. ></TABLE
  28404. >
  28405.    </P
  28406. ><DIV
  28407. CLASS="sect2"
  28408. ><HR><H3
  28409. CLASS="sect2"
  28410. ><A
  28411. NAME="functions.arguments.by-reference"
  28412. >Making arguments be passed by reference</A
  28413. ></H3
  28414. ><P
  28415. >      By default, function arguments are passed by value (so that if
  28416.      you change the value of the argument within the function, it does
  28417.      not get changed outside of the function). If you wish to allow a
  28418.      function to modify its arguments, you must pass them by
  28419.      reference.
  28420.     </P
  28421. ><P
  28422. >      If you want an argument to a function to always be passed by
  28423.      reference, you can prepend an ampersand (&) to the argument
  28424.      name in the function definition:
  28425.     </P
  28426. ><P
  28427. >      <TABLE
  28428. WIDTH="100%"
  28429. BORDER="0"
  28430. CELLPADDING="0"
  28431. CELLSPACING="0"
  28432. CLASS="EXAMPLE"
  28433. ><TR
  28434. ><TD
  28435. ><DIV
  28436. CLASS="example"
  28437. ><A
  28438. NAME="AEN5033"
  28439. ></A
  28440. ><P
  28441. ><B
  28442. >Example 17-5. Passing function parameters by reference</B
  28443. ></P
  28444. ><TABLE
  28445. BORDER="0"
  28446. BGCOLOR="#E0E0E0"
  28447. CELLPADDING="5"
  28448. ><TR
  28449. ><TD
  28450. ><PRE
  28451. CLASS="php"
  28452. ><?php
  28453. function add_some_extra(&$string)
  28454. {
  28455.     $string .= 'and something extra.';
  28456. }
  28457. $str = 'This is a string, ';
  28458. add_some_extra($str);
  28459. echo $str;    // outputs 'This is a string, and something extra.'
  28460. ?></PRE
  28461. ></TD
  28462. ></TR
  28463. ></TABLE
  28464. ></DIV
  28465. ></TD
  28466. ></TR
  28467. ></TABLE
  28468. >
  28469.     </P
  28470. ></DIV
  28471. ><DIV
  28472. CLASS="sect2"
  28473. ><HR><H3
  28474. CLASS="sect2"
  28475. ><A
  28476. NAME="functions.arguments.default"
  28477. >Default argument values</A
  28478. ></H3
  28479. ><P
  28480. >      A function may define C++-style default values for scalar
  28481.      arguments as follows:
  28482.     </P
  28483. ><P
  28484. >      <TABLE
  28485. WIDTH="100%"
  28486. BORDER="0"
  28487. CELLPADDING="0"
  28488. CELLSPACING="0"
  28489. CLASS="EXAMPLE"
  28490. ><TR
  28491. ><TD
  28492. ><DIV
  28493. CLASS="example"
  28494. ><A
  28495. NAME="AEN5040"
  28496. ></A
  28497. ><P
  28498. ><B
  28499. >Example 17-6. Use of default parameters in functions</B
  28500. ></P
  28501. ><TABLE
  28502. BORDER="0"
  28503. BGCOLOR="#E0E0E0"
  28504. CELLPADDING="5"
  28505. ><TR
  28506. ><TD
  28507. ><PRE
  28508. CLASS="php"
  28509. ><?php
  28510. function makecoffee($type = "cappuccino")
  28511. {
  28512.     return "Making a cup of $type.\n";
  28513. }
  28514. echo makecoffee();
  28515. echo makecoffee("espresso");
  28516. ?></PRE
  28517. ></TD
  28518. ></TR
  28519. ></TABLE
  28520. ></DIV
  28521. ></TD
  28522. ></TR
  28523. ></TABLE
  28524. >
  28525.     </P
  28526. ><P
  28527. >      The output from the above snippet is:
  28528.     </P
  28529. ><P
  28530. >      <TABLE
  28531. BORDER="0"
  28532. BGCOLOR="#E0E0E0"
  28533. CELLPADDING="5"
  28534. ><TR
  28535. ><TD
  28536. ><PRE
  28537. CLASS="screen"
  28538. >Making a cup of cappuccino.
  28539. Making a cup of espresso.</PRE
  28540. ></TD
  28541. ></TR
  28542. ></TABLE
  28543. >
  28544.     </P
  28545. ><P
  28546. >      Also PHP allows you to use arrays and special type NULL as  
  28547.      default values, for example:
  28548.     </P
  28549. ><P
  28550. >      <TABLE
  28551. WIDTH="100%"
  28552. BORDER="0"
  28553. CELLPADDING="0"
  28554. CELLSPACING="0"
  28555. CLASS="EXAMPLE"
  28556. ><TR
  28557. ><TD
  28558. ><DIV
  28559. CLASS="example"
  28560. ><A
  28561. NAME="AEN5048"
  28562. ></A
  28563. ><P
  28564. ><B
  28565. >Example 17-7. Using non-scalar types as default values</B
  28566. ></P
  28567. ><TABLE
  28568. BORDER="0"
  28569. BGCOLOR="#E0E0E0"
  28570. CELLPADDING="5"
  28571. ><TR
  28572. ><TD
  28573. ><PRE
  28574. CLASS="php"
  28575. ><?php
  28576. function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
  28577. {
  28578.     $device = is_null($coffeeMaker) ? "hands" : $coffeeMaker;
  28579.     return "Making a cup of ".join(", ", $types)." with $device.\n";
  28580. }
  28581. echo makecoffee();
  28582. echo makecoffee(array("cappuccino", "lavazza"), "teapot");
  28583. ?></PRE
  28584. ></TD
  28585. ></TR
  28586. ></TABLE
  28587. ></DIV
  28588. ></TD
  28589. ></TR
  28590. ></TABLE
  28591. >
  28592.     
  28593.     </P
  28594. ><P
  28595. >      The default value must be a constant expression, not (for
  28596.      example) a variable, a class member or a function call.
  28597.     </P
  28598. ><P
  28599. >      Note that when using default arguments, any defaults should be on
  28600.      the right side of any non-default arguments; otherwise, things
  28601.      will not work as expected. Consider the following code snippet:
  28602.     </P
  28603. ><P
  28604. >      <TABLE
  28605. WIDTH="100%"
  28606. BORDER="0"
  28607. CELLPADDING="0"
  28608. CELLSPACING="0"
  28609. CLASS="EXAMPLE"
  28610. ><TR
  28611. ><TD
  28612. ><DIV
  28613. CLASS="example"
  28614. ><A
  28615. NAME="AEN5054"
  28616. ></A
  28617. ><P
  28618. ><B
  28619. >Example 17-8. Incorrect usage of default function arguments</B
  28620. ></P
  28621. ><TABLE
  28622. BORDER="0"
  28623. BGCOLOR="#E0E0E0"
  28624. CELLPADDING="5"
  28625. ><TR
  28626. ><TD
  28627. ><PRE
  28628. CLASS="php"
  28629. ><?php
  28630. function makeyogurt($type = "acidophilus", $flavour)
  28631. {
  28632.     return "Making a bowl of $type $flavour.\n";
  28633. }
  28634.  
  28635. echo makeyogurt("raspberry");   // won't work as expected
  28636. ?></PRE
  28637. ></TD
  28638. ></TR
  28639. ></TABLE
  28640. ></DIV
  28641. ></TD
  28642. ></TR
  28643. ></TABLE
  28644. >
  28645.     </P
  28646. ><P
  28647. >      The output of the above example is:
  28648.     </P
  28649. ><P
  28650. >      <TABLE
  28651. BORDER="0"
  28652. BGCOLOR="#E0E0E0"
  28653. CELLPADDING="5"
  28654. ><TR
  28655. ><TD
  28656. ><PRE
  28657. CLASS="screen"
  28658. >Warning: Missing argument 2 in call to makeyogurt() in 
  28659. /usr/local/etc/httpd/htdocs/php3test/functest.html on line 41
  28660. Making a bowl of raspberry .</PRE
  28661. ></TD
  28662. ></TR
  28663. ></TABLE
  28664. >
  28665.     </P
  28666. ><P
  28667. >      Now, compare the above with this:
  28668.     </P
  28669. ><P
  28670. >      <TABLE
  28671. WIDTH="100%"
  28672. BORDER="0"
  28673. CELLPADDING="0"
  28674. CELLSPACING="0"
  28675. CLASS="EXAMPLE"
  28676. ><TR
  28677. ><TD
  28678. ><DIV
  28679. CLASS="example"
  28680. ><A
  28681. NAME="AEN5062"
  28682. ></A
  28683. ><P
  28684. ><B
  28685. >Example 17-9. Correct usage of default function arguments</B
  28686. ></P
  28687. ><TABLE
  28688. BORDER="0"
  28689. BGCOLOR="#E0E0E0"
  28690. CELLPADDING="5"
  28691. ><TR
  28692. ><TD
  28693. ><PRE
  28694. CLASS="php"
  28695. ><?php
  28696. function makeyogurt($flavour, $type = "acidophilus")
  28697. {
  28698.     return "Making a bowl of $type $flavour.\n";
  28699. }
  28700.  
  28701. echo makeyogurt("raspberry");   // works as expected
  28702. ?></PRE
  28703. ></TD
  28704. ></TR
  28705. ></TABLE
  28706. ></DIV
  28707. ></TD
  28708. ></TR
  28709. ></TABLE
  28710. >
  28711.     </P
  28712. ><P
  28713. >      The output of this example is:
  28714.     </P
  28715. ><P
  28716. >      <TABLE
  28717. BORDER="0"
  28718. BGCOLOR="#E0E0E0"
  28719. CELLPADDING="5"
  28720. ><TR
  28721. ><TD
  28722. ><PRE
  28723. CLASS="screen"
  28724. >Making a bowl of acidophilus raspberry.</PRE
  28725. ></TD
  28726. ></TR
  28727. ></TABLE
  28728. >
  28729.     </P
  28730. ><DIV
  28731. CLASS="note"
  28732. ><BLOCKQUOTE
  28733. CLASS="note"
  28734. ><P
  28735. ><B
  28736. >Note: </B
  28737. >
  28738.       As of PHP 5, default values may be passed by reference.      
  28739.      </P
  28740. ></BLOCKQUOTE
  28741. ></DIV
  28742. ></DIV
  28743. ><DIV
  28744. CLASS="sect2"
  28745. ><HR><H3
  28746. CLASS="sect2"
  28747. ><A
  28748. NAME="functions.variable-arg-list"
  28749. >Variable-length argument lists</A
  28750. ></H3
  28751. ><P
  28752. >      PHP 4 and above has support for variable-length argument lists in
  28753.      user-defined functions. This is really quite easy, using the
  28754.      <A
  28755. HREF="#function.func-num-args"
  28756. ><B
  28757. CLASS="function"
  28758. >func_num_args()</B
  28759. ></A
  28760. >,
  28761.      <A
  28762. HREF="#function.func-get-arg"
  28763. ><B
  28764. CLASS="function"
  28765. >func_get_arg()</B
  28766. ></A
  28767. >, and
  28768.      <A
  28769. HREF="#function.func-get-args"
  28770. ><B
  28771. CLASS="function"
  28772. >func_get_args()</B
  28773. ></A
  28774. > functions.
  28775.     </P
  28776. ><P
  28777. >      No special syntax is required, and argument lists may still be
  28778.      explicitly provided with function definitions and will behave as
  28779.      normal.
  28780.     </P
  28781. ></DIV
  28782. ></DIV
  28783. ><DIV
  28784. CLASS="sect1"
  28785. ><HR><H2
  28786. CLASS="sect1"
  28787. ><A
  28788. NAME="functions.returning-values"
  28789. >Returning values</A
  28790. ></H2
  28791. ><P
  28792. >     Values are returned by using the optional return statement. Any
  28793.     type may be returned, including lists and objects. This causes the
  28794.     function to end its execution immediately and pass control back to
  28795.     the line from which it was called. See <A
  28796. HREF="#function.return"
  28797. ><B
  28798. CLASS="function"
  28799. >return()</B
  28800. ></A
  28801. >
  28802.     for more information.
  28803.    </P
  28804. ><P
  28805. >     <TABLE
  28806. WIDTH="100%"
  28807. BORDER="0"
  28808. CELLPADDING="0"
  28809. CELLSPACING="0"
  28810. CLASS="EXAMPLE"
  28811. ><TR
  28812. ><TD
  28813. ><DIV
  28814. CLASS="example"
  28815. ><A
  28816. NAME="AEN5082"
  28817. ></A
  28818. ><P
  28819. ><B
  28820. >Example 17-10. Use of <A
  28821. HREF="#function.return"
  28822. ><B
  28823. CLASS="function"
  28824. >return()</B
  28825. ></A
  28826. ></B
  28827. ></P
  28828. ><TABLE
  28829. BORDER="0"
  28830. BGCOLOR="#E0E0E0"
  28831. CELLPADDING="5"
  28832. ><TR
  28833. ><TD
  28834. ><PRE
  28835. CLASS="php"
  28836. ><?php
  28837. function square($num)
  28838. {
  28839.     return $num * $num;
  28840. }
  28841. echo square(4);   // outputs '16'.
  28842. ?></PRE
  28843. ></TD
  28844. ></TR
  28845. ></TABLE
  28846. ></DIV
  28847. ></TD
  28848. ></TR
  28849. ></TABLE
  28850. >
  28851.    </P
  28852. ><P
  28853. >     You can't return multiple values from a function, but similar
  28854.     results can be obtained by returning a list.
  28855.    </P
  28856. ><P
  28857. >     <TABLE
  28858. WIDTH="100%"
  28859. BORDER="0"
  28860. CELLPADDING="0"
  28861. CELLSPACING="0"
  28862. CLASS="EXAMPLE"
  28863. ><TR
  28864. ><TD
  28865. ><DIV
  28866. CLASS="example"
  28867. ><A
  28868. NAME="AEN5088"
  28869. ></A
  28870. ><P
  28871. ><B
  28872. >Example 17-11. Returning an array to get multiple values</B
  28873. ></P
  28874. ><TABLE
  28875. BORDER="0"
  28876. BGCOLOR="#E0E0E0"
  28877. CELLPADDING="5"
  28878. ><TR
  28879. ><TD
  28880. ><PRE
  28881. CLASS="php"
  28882. ><?php
  28883. function small_numbers()
  28884. {
  28885.     return array (0, 1, 2);
  28886. }
  28887. list ($zero, $one, $two) = small_numbers();
  28888. ?></PRE
  28889. ></TD
  28890. ></TR
  28891. ></TABLE
  28892. ></DIV
  28893. ></TD
  28894. ></TR
  28895. ></TABLE
  28896. >
  28897.    </P
  28898. ><P
  28899. >     To return a reference from a function, you have to use
  28900.     the reference operator & in both the function declaration and
  28901.     when assigning the returned value to a variable:
  28902.    </P
  28903. ><P
  28904. >     <TABLE
  28905. WIDTH="100%"
  28906. BORDER="0"
  28907. CELLPADDING="0"
  28908. CELLSPACING="0"
  28909. CLASS="EXAMPLE"
  28910. ><TR
  28911. ><TD
  28912. ><DIV
  28913. CLASS="example"
  28914. ><A
  28915. NAME="AEN5093"
  28916. ></A
  28917. ><P
  28918. ><B
  28919. >Example 17-12. Returning a reference from a function</B
  28920. ></P
  28921. ><TABLE
  28922. BORDER="0"
  28923. BGCOLOR="#E0E0E0"
  28924. CELLPADDING="5"
  28925. ><TR
  28926. ><TD
  28927. ><PRE
  28928. CLASS="php"
  28929. ><?php
  28930. function &returns_reference()
  28931. {
  28932.     return $someref;
  28933. }
  28934.  
  28935. $newref =& returns_reference();
  28936. ?></PRE
  28937. ></TD
  28938. ></TR
  28939. ></TABLE
  28940. ></DIV
  28941. ></TD
  28942. ></TR
  28943. ></TABLE
  28944. >
  28945.    </P
  28946. ><P
  28947. >     For more information on references, please check out <A
  28948. HREF="#language.references"
  28949. >References Explained</A
  28950. >.
  28951.    </P
  28952. ></DIV
  28953. ><DIV
  28954. CLASS="sect1"
  28955. ><HR><H2
  28956. CLASS="sect1"
  28957. ><A
  28958. NAME="functions.variable-functions"
  28959. >Variable functions</A
  28960. ></H2
  28961. ><P
  28962. >     PHP supports the concept of variable functions. This means that if
  28963.     a variable name has parentheses appended to it, PHP will look for
  28964.     a function with the same name as whatever the variable evaluates
  28965.     to, and will attempt to execute it. Among other things, this can
  28966.     be used to implement callbacks, function tables, and so forth.
  28967.    </P
  28968. ><P
  28969. >     Variable functions won't work with language constructs such 
  28970.     as <A
  28971. HREF="#function.echo"
  28972. ><B
  28973. CLASS="function"
  28974. >echo()</B
  28975. ></A
  28976. >, <A
  28977. HREF="#function.print"
  28978. ><B
  28979. CLASS="function"
  28980. >print()</B
  28981. ></A
  28982. >,
  28983.     <A
  28984. HREF="#function.unset"
  28985. ><B
  28986. CLASS="function"
  28987. >unset()</B
  28988. ></A
  28989. >, <A
  28990. HREF="#function.isset"
  28991. ><B
  28992. CLASS="function"
  28993. >isset()</B
  28994. ></A
  28995. >,
  28996.     <A
  28997. HREF="#function.empty"
  28998. ><B
  28999. CLASS="function"
  29000. >empty()</B
  29001. ></A
  29002. >, <A
  29003. HREF="#function.include"
  29004. ><B
  29005. CLASS="function"
  29006. >include()</B
  29007. ></A
  29008. >,
  29009.     <A
  29010. HREF="#function.require"
  29011. ><B
  29012. CLASS="function"
  29013. >require()</B
  29014. ></A
  29015. > and the like. You need to use
  29016.     your own wrapper function to utilize any of these constructs
  29017.     as variable functions.
  29018.    </P
  29019. ><P
  29020. >     <TABLE
  29021. WIDTH="100%"
  29022. BORDER="0"
  29023. CELLPADDING="0"
  29024. CELLSPACING="0"
  29025. CLASS="EXAMPLE"
  29026. ><TR
  29027. ><TD
  29028. ><DIV
  29029. CLASS="example"
  29030. ><A
  29031. NAME="AEN5110"
  29032. ></A
  29033. ><P
  29034. ><B
  29035. >Example 17-13. Variable function example</B
  29036. ></P
  29037. ><TABLE
  29038. BORDER="0"
  29039. BGCOLOR="#E0E0E0"
  29040. CELLPADDING="5"
  29041. ><TR
  29042. ><TD
  29043. ><PRE
  29044. CLASS="php"
  29045. ><?php
  29046. function foo() {
  29047.     echo "In foo()<br />\n";
  29048. }
  29049.  
  29050. function bar($arg = '')
  29051. {
  29052.     echo "In bar(); argument was '$arg'.<br />\n";
  29053. }
  29054.  
  29055. // This is a wrapper function around echo
  29056. function echoit($string)
  29057. {
  29058.     echo $string;
  29059. }
  29060.  
  29061. $func = 'foo';
  29062. $func();        // This calls foo()
  29063.  
  29064. $func = 'bar';
  29065. $func('test');  // This calls bar()
  29066.  
  29067. $func = 'echoit';
  29068. $func('test');  // This calls echoit()
  29069. ?></PRE
  29070. ></TD
  29071. ></TR
  29072. ></TABLE
  29073. ></DIV
  29074. ></TD
  29075. ></TR
  29076. ></TABLE
  29077. >
  29078.    </P
  29079. ><P
  29080. >     You can also call an object's method by using the variable functions
  29081.     feature.
  29082.     <TABLE
  29083. WIDTH="100%"
  29084. BORDER="0"
  29085. CELLPADDING="0"
  29086. CELLSPACING="0"
  29087. CLASS="EXAMPLE"
  29088. ><TR
  29089. ><TD
  29090. ><DIV
  29091. CLASS="example"
  29092. ><A
  29093. NAME="AEN5114"
  29094. ></A
  29095. ><P
  29096. ><B
  29097. >Example 17-14. Variable method example</B
  29098. ></P
  29099. ><TABLE
  29100. BORDER="0"
  29101. BGCOLOR="#E0E0E0"
  29102. CELLPADDING="5"
  29103. ><TR
  29104. ><TD
  29105. ><PRE
  29106. CLASS="php"
  29107. ><?php
  29108. class Foo
  29109. {
  29110.     function Variable()
  29111.     {
  29112.         $name = 'Bar';
  29113.         $this->$name(); // This calls the Bar() method
  29114.     }
  29115.     
  29116.     function Bar()
  29117.     {
  29118.         echo "This is Bar";
  29119.     }
  29120. }
  29121.  
  29122. $foo = new Foo();
  29123. $funcname = "Variable";
  29124. $foo->$funcname();  // This calls $foo->Variable()
  29125.  
  29126. ?></PRE
  29127. ></TD
  29128. ></TR
  29129. ></TABLE
  29130. ></DIV
  29131. ></TD
  29132. ></TR
  29133. ></TABLE
  29134. >
  29135.    </P
  29136. ><P
  29137. >     See also <A
  29138. HREF="#function.call-user-func"
  29139. ><B
  29140. CLASS="function"
  29141. >call_user_func()</B
  29142. ></A
  29143. >,
  29144.     <A
  29145. HREF="#language.variables.variable"
  29146. >     variable variables</A
  29147. > and <A
  29148. HREF="#function.function-exists"
  29149. ><B
  29150. CLASS="function"
  29151. >function_exists()</B
  29152. ></A
  29153. >.
  29154.    </P
  29155. ></DIV
  29156. ><DIV
  29157. CLASS="sect1"
  29158. ><HR><H2
  29159. CLASS="sect1"
  29160. ><A
  29161. NAME="functions.internal"
  29162. >Internal (built-in) functions</A
  29163. ></H2
  29164. ><P
  29165. >     PHP comes standard with many functions and constructs.  There are also
  29166.     functions that require specific PHP extensions compiled in otherwise 
  29167.     you'll get fatal "undefined function" errors.  For example, to use 
  29168.     <A
  29169. HREF="#ref.image"
  29170. >image</A
  29171. > functions such as 
  29172.     <A
  29173. HREF="#function.imagecreatetruecolor"
  29174. ><B
  29175. CLASS="function"
  29176. >imagecreatetruecolor()</B
  29177. ></A
  29178. >, you'll need your PHP compiled
  29179.     with <SPAN
  29180. CLASS="productname"
  29181. >GD</SPAN
  29182. > support.  Or, to use <A
  29183. HREF="#function.mysql-connect"
  29184. ><B
  29185. CLASS="function"
  29186. >mysql_connect()</B
  29187. ></A
  29188. > you'll
  29189.     need your PHP compiled in with <A
  29190. HREF="#ref.mysql"
  29191. >MySQL</A
  29192. >
  29193.     support.  There are many core functions that are included in every
  29194.     version of PHP like the <A
  29195. HREF="#ref.strings"
  29196. >string</A
  29197. > and 
  29198.     <A
  29199. HREF="#ref.var"
  29200. >variable</A
  29201. > functions.  A call 
  29202.     to <A
  29203. HREF="#function.phpinfo"
  29204. ><B
  29205. CLASS="function"
  29206. >phpinfo()</B
  29207. ></A
  29208. > or
  29209.     <A
  29210. HREF="#function.get-loaded-extensions"
  29211. ><B
  29212. CLASS="function"
  29213. >get_loaded_extensions()</B
  29214. ></A
  29215. > will show you which
  29216.     extensions are loaded into your PHP.  Also note that many extensions are
  29217.     enabled by default and that the PHP manual is split up by extension.
  29218.     See the <A
  29219. HREF="#configuration"
  29220. >configuration</A
  29221. >,  
  29222.     <A
  29223. HREF="#install"
  29224. >installation</A
  29225. >, and individual
  29226.     extension chapters, for information on how to setup your PHP.
  29227.    </P
  29228. ><P
  29229. >     Reading and understanding a function's prototype is explained within the
  29230.     manual section titled 
  29231.     <A
  29232. HREF="#about.prototypes"
  29233. >how to read a function definition</A
  29234. >.
  29235.     It's important to realize what a function returns or if a function works
  29236.     directly on a passed in value.  For example,
  29237.     <A
  29238. HREF="#function.str-replace"
  29239. ><B
  29240. CLASS="function"
  29241. >str_replace()</B
  29242. ></A
  29243. > will return the modified string while 
  29244.     <A
  29245. HREF="#function.usort"
  29246. ><B
  29247. CLASS="function"
  29248. >usort()</B
  29249. ></A
  29250. > works on the actual passed in variable
  29251.     itself.  Each manual page also has specific information for each
  29252.     function like information on function parameters, behavior changes,
  29253.     return values for both success and failure, and availability information.
  29254.     Knowing these important (yet often subtle) differences is crucial for
  29255.     writing correct PHP code.
  29256.    </P
  29257. ><P
  29258. >     See also <A
  29259. HREF="#function.function-exists"
  29260. ><B
  29261. CLASS="function"
  29262. >function_exists()</B
  29263. ></A
  29264. >, 
  29265.     <A
  29266. HREF="#funcref"
  29267. >the function reference</A
  29268. >,
  29269.     <A
  29270. HREF="#function.get-extension-funcs"
  29271. ><B
  29272. CLASS="function"
  29273. >get_extension_funcs()</B
  29274. ></A
  29275. >, and 
  29276.     <A
  29277. HREF="#function.dl"
  29278. ><B
  29279. CLASS="function"
  29280. >dl()</B
  29281. ></A
  29282. >.
  29283.    </P
  29284. ></DIV
  29285. ></DIV
  29286. ><DIV
  29287. CLASS="chapter"
  29288. ><HR><H1
  29289. ><A
  29290. NAME="language.oop"
  29291. >Chapter 18. Classes and Objects (PHP 4)</A
  29292. ></H1
  29293. ><DIV
  29294. CLASS="sect1"
  29295. ><H2
  29296. CLASS="sect1"
  29297. ><A
  29298. NAME="keyword.class"
  29299. ><VAR
  29300. CLASS="literal"
  29301. >class</VAR
  29302. ></A
  29303. ></H2
  29304. ><P
  29305. >     A class is a collection of variables and functions working with
  29306.     these variables.  A class is defined using the following syntax:
  29307.    </P
  29308. ><P
  29309. >     <DIV
  29310. CLASS="informalexample"
  29311. ><P
  29312. ></P
  29313. ><A
  29314. NAME="AEN5151"
  29315. ></A
  29316. ><TABLE
  29317. BORDER="0"
  29318. BGCOLOR="#E0E0E0"
  29319. CELLPADDING="5"
  29320. ><TR
  29321. ><TD
  29322. ><PRE
  29323. CLASS="php"
  29324. ><?php
  29325. class Cart {
  29326.     var $items;  // Items in our shopping cart
  29327.  
  29328.     // Add $num articles of $artnr to the cart
  29329.  
  29330.     function add_item($artnr, $num) {
  29331.         $this->items[$artnr] += $num;
  29332.     }
  29333.  
  29334.     // Take $num articles of $artnr out of the cart
  29335.  
  29336.     function remove_item($artnr, $num) {
  29337.         if ($this->items[$artnr] > $num) {
  29338.             $this->items[$artnr] -= $num;
  29339.             return true;
  29340.         } elseif ($this->items[$artnr] == $num) {
  29341.             unset($this->items[$artnr]);
  29342.             return true;
  29343.         } else {
  29344.             return false;
  29345.         }
  29346.     }
  29347. }
  29348. ?></PRE
  29349. ></TD
  29350. ></TR
  29351. ></TABLE
  29352. ><P
  29353. ></P
  29354. ></DIV
  29355. >
  29356.    </P
  29357. ><P
  29358. >     This defines a class named Cart that consists of an associative
  29359.     array of articles in the cart and two functions to add and remove
  29360.     items from this cart.
  29361.    </P
  29362. ><DIV
  29363. CLASS="warning"
  29364. ><P
  29365. ></P
  29366. ><TABLE
  29367. CLASS="warning"
  29368. BORDER="1"
  29369. WIDTH="100%"
  29370. ><TR
  29371. ><TD
  29372. ALIGN="CENTER"
  29373. ><B
  29374. >Warning</B
  29375. ></TD
  29376. ></TR
  29377. ><TR
  29378. ><TD
  29379. ALIGN="LEFT"
  29380. ><P
  29381. >      You can <SPAN
  29382. CLASS="emphasis"
  29383. ><I
  29384. CLASS="emphasis"
  29385. >NOT</I
  29386. ></SPAN
  29387. > break up a class definition into
  29388.      multiple files. You also can <SPAN
  29389. CLASS="emphasis"
  29390. ><I
  29391. CLASS="emphasis"
  29392. >NOT</I
  29393. ></SPAN
  29394. > break a class
  29395.      definition into multiple PHP blocks, unless the break is within a method
  29396.      declaration. The following will not work:
  29397.     </P
  29398. ><P
  29399. >      <DIV
  29400. CLASS="informalexample"
  29401. ><P
  29402. ></P
  29403. ><A
  29404. NAME="AEN5159"
  29405. ></A
  29406. ><TABLE
  29407. BORDER="0"
  29408. BGCOLOR="#E0E0E0"
  29409. CELLPADDING="5"
  29410. ><TR
  29411. ><TD
  29412. ><PRE
  29413. CLASS="php"
  29414. ><?php
  29415. class test {
  29416. ?>
  29417. <?php
  29418.     function test() {
  29419.         print 'OK';
  29420.     }
  29421. }
  29422. ?></PRE
  29423. ></TD
  29424. ></TR
  29425. ></TABLE
  29426. ><P
  29427. ></P
  29428. ></DIV
  29429. >
  29430.     </P
  29431. ><P
  29432. >      However, the following is allowed:
  29433.     </P
  29434. ><P
  29435. >      <DIV
  29436. CLASS="informalexample"
  29437. ><P
  29438. ></P
  29439. ><A
  29440. NAME="AEN5163"
  29441. ></A
  29442. ><TABLE
  29443. BORDER="0"
  29444. BGCOLOR="#E0E0E0"
  29445. CELLPADDING="5"
  29446. ><TR
  29447. ><TD
  29448. ><PRE
  29449. CLASS="php"
  29450. ><?php
  29451. class test {
  29452.     function test() {
  29453.         ?>
  29454.         <?php
  29455.         print 'OK';
  29456.     }
  29457. }
  29458. ?></PRE
  29459. ></TD
  29460. ></TR
  29461. ></TABLE
  29462. ><P
  29463. ></P
  29464. ></DIV
  29465. >
  29466.     </P
  29467. ></TD
  29468. ></TR
  29469. ></TABLE
  29470. ></DIV
  29471. ><P
  29472. >     The following cautionary notes are valid for PHP 4.
  29473.    </P
  29474. ><DIV
  29475. CLASS="caution"
  29476. ><P
  29477. ></P
  29478. ><TABLE
  29479. CLASS="caution"
  29480. BORDER="1"
  29481. WIDTH="100%"
  29482. ><TR
  29483. ><TD
  29484. ALIGN="CENTER"
  29485. ><B
  29486. >Caution</B
  29487. ></TD
  29488. ></TR
  29489. ><TR
  29490. ><TD
  29491. ALIGN="LEFT"
  29492. ><P
  29493. >      The name <VAR
  29494. CLASS="literal"
  29495. >stdClass</VAR
  29496. > is used interally by
  29497.      Zend and is reserved. You cannot have a class named
  29498.      <VAR
  29499. CLASS="literal"
  29500. >stdClass</VAR
  29501. > in PHP.
  29502.     </P
  29503. ></TD
  29504. ></TR
  29505. ></TABLE
  29506. ></DIV
  29507. ><DIV
  29508. CLASS="caution"
  29509. ><P
  29510. ></P
  29511. ><TABLE
  29512. CLASS="caution"
  29513. BORDER="1"
  29514. WIDTH="100%"
  29515. ><TR
  29516. ><TD
  29517. ALIGN="CENTER"
  29518. ><B
  29519. >Caution</B
  29520. ></TD
  29521. ></TR
  29522. ><TR
  29523. ><TD
  29524. ALIGN="LEFT"
  29525. ><P
  29526. >       The function names <VAR
  29527. CLASS="literal"
  29528. >__sleep</VAR
  29529. > and
  29530.       <VAR
  29531. CLASS="literal"
  29532. >__wakeup</VAR
  29533. > are magical in PHP classes. You
  29534.       cannot have functions with these names in any of your
  29535.       classes unless you want the magic functionality associated
  29536.       with them. See below for more information.
  29537.     </P
  29538. ></TD
  29539. ></TR
  29540. ></TABLE
  29541. ></DIV
  29542. ><DIV
  29543. CLASS="caution"
  29544. ><P
  29545. ></P
  29546. ><TABLE
  29547. CLASS="caution"
  29548. BORDER="1"
  29549. WIDTH="100%"
  29550. ><TR
  29551. ><TD
  29552. ALIGN="CENTER"
  29553. ><B
  29554. >Caution</B
  29555. ></TD
  29556. ></TR
  29557. ><TR
  29558. ><TD
  29559. ALIGN="LEFT"
  29560. ><P
  29561. >       PHP reserves all function names starting with __ as magical.
  29562.       It is recommended that you do not use function names with
  29563.       __ in PHP unless you want some documented magic functionality.
  29564.     </P
  29565. ></TD
  29566. ></TR
  29567. ></TABLE
  29568. ></DIV
  29569. ><P
  29570. >     In PHP 4, only constant initializers for <VAR
  29571. CLASS="literal"
  29572. >var</VAR
  29573. >
  29574.     variables are allowed. To initialize variables with non-constant
  29575.     values, you need an initialization function which is called
  29576.     automatically when an object is being constructed from the
  29577.     class. Such a function is called a constructor (see below).
  29578.    </P
  29579. ><DIV
  29580. CLASS="informalexample"
  29581. ><P
  29582. ></P
  29583. ><A
  29584. NAME="AEN5178"
  29585. ></A
  29586. ><TABLE
  29587. BORDER="0"
  29588. BGCOLOR="#E0E0E0"
  29589. CELLPADDING="5"
  29590. ><TR
  29591. ><TD
  29592. ><PRE
  29593. CLASS="php"
  29594. ><?php
  29595. class Cart {
  29596.     /* None of these will work in PHP 4. */
  29597.     var $todays_date = date("Y-m-d");
  29598.     var $name = $firstname;
  29599.     var $owner = 'Fred ' . 'Jones';
  29600.     /* Arrays containing constant values will, though. */
  29601.     var $items = array("VCR", "TV");
  29602. }
  29603.  
  29604. /* This is how it should be done. */
  29605. class Cart {
  29606.     var $todays_date;
  29607.     var $name;
  29608.     var $owner;
  29609.     var $items = array("VCR", "TV");
  29610.  
  29611.     function Cart() {
  29612.         $this->todays_date = date("Y-m-d");
  29613.         $this->name = $GLOBALS['firstname'];
  29614.         /* etc. . . */
  29615.     }
  29616. }
  29617. ?></PRE
  29618. ></TD
  29619. ></TR
  29620. ></TABLE
  29621. ><P
  29622. ></P
  29623. ></DIV
  29624. ><P
  29625. >     Classes are types, that is, they are blueprints for actual
  29626.     variables. You have to create a variable of the desired type with
  29627.     the <VAR
  29628. CLASS="literal"
  29629. >new</VAR
  29630. > operator.
  29631.    </P
  29632. ><DIV
  29633. CLASS="informalexample"
  29634. ><P
  29635. ></P
  29636. ><A
  29637. NAME="AEN5182"
  29638. ></A
  29639. ><TABLE
  29640. BORDER="0"
  29641. BGCOLOR="#E0E0E0"
  29642. CELLPADDING="5"
  29643. ><TR
  29644. ><TD
  29645. ><PRE
  29646. CLASS="php"
  29647. ><?php
  29648. $cart = new Cart;
  29649. $cart->add_item("10", 1);
  29650.  
  29651. $another_cart = new Cart;
  29652. $another_cart->add_item("0815", 3);
  29653. ?></PRE
  29654. ></TD
  29655. ></TR
  29656. ></TABLE
  29657. ><P
  29658. ></P
  29659. ></DIV
  29660. ><P
  29661. >     This creates the objects <VAR
  29662. CLASS="varname"
  29663. >$cart</VAR
  29664. > and
  29665.     <VAR
  29666. CLASS="varname"
  29667. >$another_cart</VAR
  29668. >, both of the class Cart. The function
  29669.     add_item() of the <VAR
  29670. CLASS="varname"
  29671. >$cart</VAR
  29672. > object is being called to add 1
  29673.     item of article number 10 to the <VAR
  29674. CLASS="varname"
  29675. >$cart</VAR
  29676. >. 3 items of
  29677.     article number 0815 are being added to <VAR
  29678. CLASS="varname"
  29679. >$another_cart</VAR
  29680. >.
  29681.    </P
  29682. ><P
  29683. >     Both, <VAR
  29684. CLASS="varname"
  29685. >$cart</VAR
  29686. > and <VAR
  29687. CLASS="varname"
  29688. >$another_cart</VAR
  29689. >, have
  29690.     functions add_item(), remove_item() and a variable items. These are
  29691.     distinct functions and variables. You can think of the objects as
  29692.     something similar to directories in a filesystem. In a filesystem you can
  29693.     have two different files <TT
  29694. CLASS="filename"
  29695. >README.TXT</TT
  29696. >, as long as they are in different
  29697.     directories.  Just like with directories where you'll have to type the
  29698.     full pathname in order to reach each file from the toplevel directory, you
  29699.     have to specify the complete name of the function you want to call: In PHP
  29700.     terms, the toplevel directory would be the global namespace, and the
  29701.     pathname separator would be <VAR
  29702. CLASS="literal"
  29703. >-></VAR
  29704. >.  Thus, the names
  29705.     <VAR
  29706. CLASS="varname"
  29707. >$cart->items</VAR
  29708. > and
  29709.     <VAR
  29710. CLASS="varname"
  29711. >$another_cart->items</VAR
  29712. > name two different variables.
  29713.     Note that the variable is named <VAR
  29714. CLASS="varname"
  29715. >$cart->items</VAR
  29716. >, not
  29717.     <VAR
  29718. CLASS="varname"
  29719. >$cart->$items</VAR
  29720. >, that is, a variable name in PHP has
  29721.     only a single dollar sign.
  29722.    </P
  29723. ><DIV
  29724. CLASS="informalexample"
  29725. ><P
  29726. ></P
  29727. ><A
  29728. NAME="AEN5199"
  29729. ></A
  29730. ><TABLE
  29731. BORDER="0"
  29732. BGCOLOR="#E0E0E0"
  29733. CELLPADDING="5"
  29734. ><TR
  29735. ><TD
  29736. ><PRE
  29737. CLASS="php"
  29738. ><?php
  29739. // correct, single $
  29740. $cart->items = array("10" => 1); 
  29741.  
  29742. // invalid, because $cart->$items becomes $cart->""
  29743. $cart->$items = array("10" => 1);
  29744.  
  29745. // correct, but may or may not be what was intended:
  29746. // $cart->$myvar becomes $cart->items
  29747. $myvar = 'items';
  29748. $cart->$myvar = array("10" => 1);  
  29749. ?></PRE
  29750. ></TD
  29751. ></TR
  29752. ></TABLE
  29753. ><P
  29754. ></P
  29755. ></DIV
  29756. ><P
  29757. >     Within a class definition, you do not know under which name the object
  29758.     will be accessible in your program: at the time the Cart class was
  29759.     written, it was unknown that the object will be named
  29760.     <VAR
  29761. CLASS="varname"
  29762. >$cart</VAR
  29763. > or <VAR
  29764. CLASS="varname"
  29765. >$another_cart</VAR
  29766. > later. Thus,
  29767.     you cannot write <VAR
  29768. CLASS="varname"
  29769. >$cart->items</VAR
  29770. > within the Cart class
  29771.     itself. Instead, in order to be able to access it's own functions and
  29772.     variables from within a class, one can use the pseudo-variable
  29773.     <VAR
  29774. CLASS="varname"
  29775. >$this</VAR
  29776. > which can be read as 'my own' or 'current
  29777.     object'. Thus, '<VAR
  29778. CLASS="varname"
  29779. >$this->items[$artnr]</VAR
  29780. > +=
  29781.     <VAR
  29782. CLASS="varname"
  29783. >$num</VAR
  29784. >' can be read as 'add <VAR
  29785. CLASS="varname"
  29786. >$num</VAR
  29787. > to
  29788.     the <VAR
  29789. CLASS="varname"
  29790. >$artnr</VAR
  29791. > counter of my own items array' or 'add
  29792.     <VAR
  29793. CLASS="varname"
  29794. >$num</VAR
  29795. > to the <VAR
  29796. CLASS="varname"
  29797. >$artnr</VAR
  29798. > counter of the
  29799.     items array within the current object'.
  29800.    </P
  29801. ><DIV
  29802. CLASS="note"
  29803. ><BLOCKQUOTE
  29804. CLASS="note"
  29805. ><P
  29806. ><B
  29807. >Note: </B
  29808. >
  29809.     There are some nice functions to handle classes and objects. You might want
  29810.     to take a look at the <A
  29811. HREF="#ref.classobj"
  29812. >Class/Object
  29813.     Functions</A
  29814. >.
  29815.     </P
  29816. ></BLOCKQUOTE
  29817. ></DIV
  29818. ></DIV
  29819. ><DIV
  29820. CLASS="sect1"
  29821. ><HR><H2
  29822. CLASS="sect1"
  29823. ><A
  29824. NAME="keyword.extends"
  29825. ><VAR
  29826. CLASS="literal"
  29827. >extends</VAR
  29828. ></A
  29829. ></H2
  29830. ><P
  29831. >     Often you need classes with similar variables and functions
  29832.     to another existing class. In fact, it is good practice to
  29833.     define a generic class which can be used in all your
  29834.     projects and adapt this class for the needs of each of your
  29835.     specific projects. To facilitate this, classes can be
  29836.     extensions of other classes.  The extended or derived class
  29837.     has all variables and functions of the base class (this is
  29838.     called 'inheritance' despite the fact that nobody died) and what
  29839.     you add in the extended definition. It is not possible to
  29840.     subtract from a class, that is, to undefine any existing 
  29841.     functions or variables. An extended class is always dependent
  29842.     on a single base class, that is, multiple inheritance is
  29843.     not supported. Classes are extended using the keyword 'extends'.
  29844.    </P
  29845. ><DIV
  29846. CLASS="informalexample"
  29847. ><P
  29848. ></P
  29849. ><A
  29850. NAME="AEN5219"
  29851. ></A
  29852. ><TABLE
  29853. BORDER="0"
  29854. BGCOLOR="#E0E0E0"
  29855. CELLPADDING="5"
  29856. ><TR
  29857. ><TD
  29858. ><PRE
  29859. CLASS="php"
  29860. ><?php
  29861. class Named_Cart extends Cart {
  29862.     var $owner;
  29863.   
  29864.     function set_owner ($name) {
  29865.         $this->owner = $name;
  29866.     }
  29867. }
  29868. ?></PRE
  29869. ></TD
  29870. ></TR
  29871. ></TABLE
  29872. ><P
  29873. ></P
  29874. ></DIV
  29875. ><P
  29876. >     This defines a class Named_Cart that has all variables and functions of
  29877.     Cart plus an additional variable <VAR
  29878. CLASS="varname"
  29879. >$owner</VAR
  29880. > and an
  29881.     additional function set_owner(). You create a named cart the usual way and
  29882.     can now set and get the carts owner. You can still use normal cart
  29883.     functions on named carts:
  29884.    </P
  29885. ><DIV
  29886. CLASS="informalexample"
  29887. ><P
  29888. ></P
  29889. ><A
  29890. NAME="AEN5223"
  29891. ></A
  29892. ><TABLE
  29893. BORDER="0"
  29894. BGCOLOR="#E0E0E0"
  29895. CELLPADDING="5"
  29896. ><TR
  29897. ><TD
  29898. ><PRE
  29899. CLASS="php"
  29900. ><?php
  29901. $ncart = new Named_Cart;    // Create a named cart
  29902. $ncart->set_owner("kris");  // Name that cart
  29903. print $ncart->owner;        // print the cart owners name
  29904. $ncart->add_item("10", 1);  // (inherited functionality from cart)
  29905. ?></PRE
  29906. ></TD
  29907. ></TR
  29908. ></TABLE
  29909. ><P
  29910. ></P
  29911. ></DIV
  29912. ><P
  29913. >     This is also called a "parent-child" relationship. You create a class,
  29914.     parent, and use <VAR
  29915. CLASS="literal"
  29916. >extends</VAR
  29917. > to create a new class
  29918.     <SPAN
  29919. CLASS="emphasis"
  29920. ><I
  29921. CLASS="emphasis"
  29922. >based</I
  29923. ></SPAN
  29924. > on the parent class: the child class. You can
  29925.     even use this new child class and create another class based on this child
  29926.     class.
  29927.    </P
  29928. ><DIV
  29929. CLASS="note"
  29930. ><BLOCKQUOTE
  29931. CLASS="note"
  29932. ><P
  29933. ><B
  29934. >Note: </B
  29935. >
  29936.      Classes must be defined before they are used! If you want the class
  29937.      <VAR
  29938. CLASS="literal"
  29939. >Named_Cart</VAR
  29940. > to extend the class
  29941.      <VAR
  29942. CLASS="literal"
  29943. >Cart</VAR
  29944. >, you will have to define the class
  29945.      <VAR
  29946. CLASS="literal"
  29947. >Cart</VAR
  29948. > first. If you want to create another class called
  29949.      <VAR
  29950. CLASS="literal"
  29951. >Yellow_named_cart</VAR
  29952. > based on the class
  29953.      <VAR
  29954. CLASS="literal"
  29955. >Named_Cart</VAR
  29956. > you have to define
  29957.      <VAR
  29958. CLASS="literal"
  29959. >Named_Cart</VAR
  29960. > first. To make it short: the order in which
  29961.      the classes are defined is important.
  29962.     </P
  29963. ></BLOCKQUOTE
  29964. ></DIV
  29965. ></DIV
  29966. ><DIV
  29967. CLASS="sect1"
  29968. ><HR><H2
  29969. CLASS="sect1"
  29970. ><A
  29971. NAME="language.oop.constructor"
  29972. ><VAR
  29973. CLASS="literal"
  29974. >Constructors</VAR
  29975. ></A
  29976. ></H2
  29977. ><DIV
  29978. CLASS="caution"
  29979. ><P
  29980. ></P
  29981. ><TABLE
  29982. CLASS="caution"
  29983. BORDER="1"
  29984. WIDTH="100%"
  29985. ><TR
  29986. ><TD
  29987. ALIGN="CENTER"
  29988. ><B
  29989. >Caution</B
  29990. ></TD
  29991. ></TR
  29992. ><TR
  29993. ><TD
  29994. ALIGN="LEFT"
  29995. ><P
  29996. >      In PHP 3 and PHP 4 constructors behave differently. The PHP 4
  29997.      semantics are strongly preferred.
  29998.     </P
  29999. ></TD
  30000. ></TR
  30001. ></TABLE
  30002. ></DIV
  30003. ><P
  30004. >     Constructors are functions in a class that are automatically
  30005.     called when you create a new instance of a class with
  30006.     <VAR
  30007. CLASS="literal"
  30008. >new</VAR
  30009. >. In PHP 3, a
  30010.     function becomes a constructor when it has the same name as 
  30011.     the class. In PHP 4, a function becomes a constructor, when
  30012.     it has the same name as the class it is defined in - the
  30013.     difference is subtle, but crucial (see below).
  30014.    </P
  30015. ><DIV
  30016. CLASS="informalexample"
  30017. ><P
  30018. ></P
  30019. ><A
  30020. NAME="AEN5243"
  30021. ></A
  30022. ><TABLE
  30023. BORDER="0"
  30024. BGCOLOR="#E0E0E0"
  30025. CELLPADDING="5"
  30026. ><TR
  30027. ><TD
  30028. ><PRE
  30029. CLASS="php"
  30030. ><?php
  30031. // Works in PHP 3 and PHP 4.
  30032. class Auto_Cart extends Cart {
  30033.     function Auto_Cart() {
  30034.         $this->add_item("10", 1);
  30035.     }
  30036. }
  30037. ?></PRE
  30038. ></TD
  30039. ></TR
  30040. ></TABLE
  30041. ><P
  30042. ></P
  30043. ></DIV
  30044. ><P
  30045. >     This defines a class Auto_Cart that is a Cart plus a constructor
  30046.     which initializes the cart with one item of article number "10"
  30047.     each time a new Auto_Cart is being made with "new". Constructors
  30048.     can take arguments and these arguments can be optional, which
  30049.     makes them much more useful. To be able to still use the class
  30050.     without parameters, all parameters to constructors should be
  30051.     made optional by providing default values.
  30052.    </P
  30053. ><DIV
  30054. CLASS="informalexample"
  30055. ><P
  30056. ></P
  30057. ><A
  30058. NAME="AEN5246"
  30059. ></A
  30060. ><TABLE
  30061. BORDER="0"
  30062. BGCOLOR="#E0E0E0"
  30063. CELLPADDING="5"
  30064. ><TR
  30065. ><TD
  30066. ><PRE
  30067. CLASS="php"
  30068. ><?php
  30069. // Works in PHP 3 and PHP 4.
  30070. class Constructor_Cart extends Cart {
  30071.     function Constructor_Cart($item = "10", $num = 1) {
  30072.         $this->add_item ($item, $num);
  30073.     }
  30074. }
  30075.  
  30076. // Shop the same old boring stuff.
  30077.  
  30078. $default_cart = new Constructor_Cart;
  30079.  
  30080. // Shop for real...
  30081.  
  30082. $different_cart = new Constructor_Cart("20", 17);
  30083. ?></PRE
  30084. ></TD
  30085. ></TR
  30086. ></TABLE
  30087. ><P
  30088. ></P
  30089. ></DIV
  30090. ><P
  30091. >     You also can use the <VAR
  30092. CLASS="literal"
  30093. >@</VAR
  30094. > operator to
  30095.     <SPAN
  30096. CLASS="emphasis"
  30097. ><I
  30098. CLASS="emphasis"
  30099. >mute</I
  30100. ></SPAN
  30101. > errors occurring in the constructor, e.g.
  30102.     <VAR
  30103. CLASS="literal"
  30104. >@new</VAR
  30105. >.
  30106.    </P
  30107. ><DIV
  30108. CLASS="caution"
  30109. ><P
  30110. ></P
  30111. ><TABLE
  30112. CLASS="caution"
  30113. BORDER="1"
  30114. WIDTH="100%"
  30115. ><TR
  30116. ><TD
  30117. ALIGN="CENTER"
  30118. ><B
  30119. >Caution</B
  30120. ></TD
  30121. ></TR
  30122. ><TR
  30123. ><TD
  30124. ALIGN="LEFT"
  30125. ><P
  30126. >      In PHP 3, derived classes and constructors have a number of
  30127.      limitations. The following examples should be read carefully
  30128.      to understand these limitations.
  30129.     </P
  30130. ></TD
  30131. ></TR
  30132. ></TABLE
  30133. ></DIV
  30134. ><DIV
  30135. CLASS="informalexample"
  30136. ><P
  30137. ></P
  30138. ><A
  30139. NAME="AEN5254"
  30140. ></A
  30141. ><TABLE
  30142. BORDER="0"
  30143. BGCOLOR="#E0E0E0"
  30144. CELLPADDING="5"
  30145. ><TR
  30146. ><TD
  30147. ><PRE
  30148. CLASS="php"
  30149. ><?php
  30150. class A {
  30151.     function A() {
  30152.       echo "I am the constructor of A.<br />\n";
  30153.     }
  30154. }
  30155.  
  30156. class B extends A {
  30157.     function C() {
  30158.         echo "I am a regular function.<br />\n";
  30159.     }
  30160. }
  30161.  
  30162. // no constructor is being called in PHP 3.
  30163. $b = new B;
  30164. ?></PRE
  30165. ></TD
  30166. ></TR
  30167. ></TABLE
  30168. ><P
  30169. ></P
  30170. ></DIV
  30171. ><P
  30172. >     In PHP 3, no constructor is being called in the above example.
  30173.     The rule in PHP 3 is: 'A constructor is a function of the same
  30174.     name as the class.'. The name of the class is B, and there is
  30175.     no function called B() in class B. Nothing happens.
  30176.    </P
  30177. ><P
  30178. >     This is fixed in PHP 4 by introducing another rule: If a class
  30179.     has no constructor, the constructor of the base class is being
  30180.     called, if it exists. The above example would have printed
  30181.     'I am the constructor of A.<br />' in PHP 4.
  30182.    </P
  30183. ><DIV
  30184. CLASS="informalexample"
  30185. ><P
  30186. ></P
  30187. ><A
  30188. NAME="AEN5258"
  30189. ></A
  30190. ><TABLE
  30191. BORDER="0"
  30192. BGCOLOR="#E0E0E0"
  30193. CELLPADDING="5"
  30194. ><TR
  30195. ><TD
  30196. ><PRE
  30197. CLASS="php"
  30198. ><?php
  30199. class A
  30200. {
  30201.     function A()
  30202.     {
  30203.         echo "I am the constructor of A.<br />\n";
  30204.     }
  30205.  
  30206.     function B()
  30207.     {
  30208.         echo "I am a regular function named B in class A.<br />\n";
  30209.         echo "I am not a constructor in A.<br />\n";
  30210.     }
  30211. }
  30212.  
  30213. class B extends A
  30214. {
  30215.     function C()
  30216.     {
  30217.         echo "I am a regular function.<br />\n";
  30218.     }
  30219. }
  30220.  
  30221. // This will call B() as a constructor.
  30222. $b = new B;
  30223. ?></PRE
  30224. ></TD
  30225. ></TR
  30226. ></TABLE
  30227. ><P
  30228. ></P
  30229. ></DIV
  30230. ><P
  30231. >     In PHP 3, the function B() in class A will suddenly become a
  30232.     constructor in class B, although it was never intended to be.
  30233.     The rule in PHP 3 is: 'A constructor is a function of the same
  30234.     name as the class.'. PHP 3 does not care if the function is
  30235.     being defined in class B, or if it has been inherited.
  30236.    </P
  30237. ><P
  30238. >     This is fixed in PHP 4 by modifying the rule to: 'A constructor
  30239.     is a function of the same name as the class it is being defined
  30240.     in.'. Thus in PHP 4, the class B would have no constructor function
  30241.     of its own and the constructor of the base class would have been
  30242.     called, printing 'I am the constructor of A.<br />'.
  30243.    </P
  30244. ><DIV
  30245. CLASS="caution"
  30246. ><P
  30247. ></P
  30248. ><TABLE
  30249. CLASS="caution"
  30250. BORDER="1"
  30251. WIDTH="100%"
  30252. ><TR
  30253. ><TD
  30254. ALIGN="CENTER"
  30255. ><B
  30256. >Caution</B
  30257. ></TD
  30258. ></TR
  30259. ><TR
  30260. ><TD
  30261. ALIGN="LEFT"
  30262. ><P
  30263. >      Neither PHP 3 nor PHP 4 call constructors of the base class 
  30264.      automatically from a constructor of a derived class. It is
  30265.      your responsibility to propagate the call to constructors
  30266.      upstream where appropriate.
  30267.     </P
  30268. ></TD
  30269. ></TR
  30270. ></TABLE
  30271. ></DIV
  30272. ><DIV
  30273. CLASS="note"
  30274. ><BLOCKQUOTE
  30275. CLASS="note"
  30276. ><P
  30277. ><B
  30278. >Note: </B
  30279. >
  30280.      There are no destructors in PHP 3 or PHP 4. You may use
  30281.      <A
  30282. HREF="#function.register-shutdown-function"
  30283. ><B
  30284. CLASS="function"
  30285. >register_shutdown_function()</B
  30286. ></A
  30287. > instead
  30288.      to simulate most effects of destructors.
  30289.     </P
  30290. ></BLOCKQUOTE
  30291. ></DIV
  30292. ><P
  30293. >     Destructors are functions that are called automatically
  30294.     when an object is destroyed, either with <A
  30295. HREF="#function.unset"
  30296. ><B
  30297. CLASS="function"
  30298. >unset()</B
  30299. ></A
  30300. >
  30301.     or by simply going out of scope. There are no destructors
  30302.     in PHP.
  30303.    </P
  30304. ></DIV
  30305. ><DIV
  30306. CLASS="sect1"
  30307. ><HR><H2
  30308. CLASS="sect1"
  30309. ><A
  30310. NAME="keyword.paamayim-nekudotayim"
  30311. >Scope Resolution Operator (<VAR
  30312. CLASS="literal"
  30313. >::</VAR
  30314. >)</A
  30315. ></H2
  30316. ><DIV
  30317. CLASS="caution"
  30318. ><P
  30319. ></P
  30320. ><TABLE
  30321. CLASS="caution"
  30322. BORDER="1"
  30323. WIDTH="100%"
  30324. ><TR
  30325. ><TD
  30326. ALIGN="CENTER"
  30327. ><B
  30328. >Caution</B
  30329. ></TD
  30330. ></TR
  30331. ><TR
  30332. ><TD
  30333. ALIGN="LEFT"
  30334. ><P
  30335. >      The following is valid for PHP 4 and later only.
  30336.     </P
  30337. ></TD
  30338. ></TR
  30339. ></TABLE
  30340. ></DIV
  30341. ><P
  30342. >     Sometimes it is useful to refer to functions and variables
  30343.     in base classes or to refer to functions in classes that
  30344.     have not yet any instances. The :: operator is being used
  30345.     for this.
  30346.    </P
  30347. ><DIV
  30348. CLASS="informalexample"
  30349. ><P
  30350. ></P
  30351. ><A
  30352. NAME="AEN5275"
  30353. ></A
  30354. ><TABLE
  30355. BORDER="0"
  30356. BGCOLOR="#E0E0E0"
  30357. CELLPADDING="5"
  30358. ><TR
  30359. ><TD
  30360. ><PRE
  30361. CLASS="php"
  30362. ><?php
  30363. class A {
  30364.     function example() {
  30365.         echo "I am the original function A::example().<br />\n";
  30366.     }
  30367. }
  30368.  
  30369. class B extends A {
  30370.     function example() {
  30371.         echo "I am the redefined function B::example().<br />\n";
  30372.         A::example();
  30373.     }
  30374. }
  30375.  
  30376. // there is no object of class A.
  30377. // this will print
  30378. //   I am the original function A::example().<br />
  30379. A::example();
  30380.  
  30381. // create an object of class B.
  30382. $b = new B;
  30383.  
  30384. // this will print 
  30385. //   I am the redefined function B::example().<br />
  30386. //   I am the original function A::example().<br />
  30387. $b->example();
  30388. ?></PRE
  30389. ></TD
  30390. ></TR
  30391. ></TABLE
  30392. ><P
  30393. ></P
  30394. ></DIV
  30395. ><P
  30396. >     The above example calls the function example() in
  30397.     class A, but there is no object of class A, so that
  30398.     we cannot write $a->example() or similar. Instead we
  30399.     call example() as a 'class function', that is, as a
  30400.     function of the class itself, not any object of that
  30401.     class.
  30402.    </P
  30403. ><P
  30404. >     There are class functions, but there are no class variables.
  30405.     In fact, there is no object at all at the time of the call.
  30406.     Thus, a class function may not use any object variables (but
  30407.     it can use local and global variables), and it may no use
  30408.     <VAR
  30409. CLASS="varname"
  30410. >$this</VAR
  30411. > at all.
  30412.    </P
  30413. ><P
  30414. >     In the above example, class B redefines the function example(). 
  30415.     The original definition in class A is shadowed
  30416.     and no longer available, unless you are referring specifically
  30417.     to the implementation of example() in class A using the 
  30418.     ::-operator. Write A::example() to do this (in fact, you
  30419.     should be writing parent::example(), as shown in the next
  30420.     section).
  30421.    </P
  30422. ><P
  30423. >     In this context, there is a current object and it may have object
  30424.     variables. Thus, when used from WITHIN an object function, you may use
  30425.     <VAR
  30426. CLASS="varname"
  30427. >$this</VAR
  30428. > and object variables.
  30429.    </P
  30430. ></DIV
  30431. ><DIV
  30432. CLASS="sect1"
  30433. ><HR><H2
  30434. CLASS="sect1"
  30435. ><A
  30436. NAME="keyword.parent"
  30437. ><VAR
  30438. CLASS="literal"
  30439. >parent</VAR
  30440. ></A
  30441. ></H2
  30442. ><P
  30443. >    You may find yourself writing code that refers to
  30444.    variables and functions in base classes. This is
  30445.    particularly true if your derived class is a refinement
  30446.    or specialisation of code in your base class. 
  30447.   </P
  30448. ><P
  30449. >    Instead of using the literal name of the base class in your
  30450.    code, you should be using the special name
  30451.    <VAR
  30452. CLASS="literal"
  30453. >parent</VAR
  30454. >, which refers to the name of your
  30455.    base class as given in the <VAR
  30456. CLASS="literal"
  30457. >extends</VAR
  30458. >
  30459.    declaration of your class. By doing this, you avoid using the
  30460.    name of your base class in more than one place. Should
  30461.    your inheritance tree change during implementation, the
  30462.    change is easily made by simply changing the 
  30463.    <VAR
  30464. CLASS="literal"
  30465. >extends</VAR
  30466. > declaration of your class.
  30467.   </P
  30468. ><DIV
  30469. CLASS="informalexample"
  30470. ><P
  30471. ></P
  30472. ><A
  30473. NAME="AEN5291"
  30474. ></A
  30475. ><TABLE
  30476. BORDER="0"
  30477. BGCOLOR="#E0E0E0"
  30478. CELLPADDING="5"
  30479. ><TR
  30480. ><TD
  30481. ><PRE
  30482. CLASS="php"
  30483. ><?php
  30484. class A {
  30485.     function example() {
  30486.         echo "I am A::example() and provide basic functionality.<br />\n";
  30487.     }
  30488. }
  30489.  
  30490. class B extends A {
  30491.     function example() {
  30492.         echo "I am B::example() and provide additional functionality.<br />\n";
  30493.         parent::example();
  30494.     }
  30495. }
  30496.  
  30497. $b = new B;
  30498.  
  30499. // This will call B::example(), which will in turn call A::example().
  30500. $b->example();
  30501. ?></PRE
  30502. ></TD
  30503. ></TR
  30504. ></TABLE
  30505. ><P
  30506. ></P
  30507. ></DIV
  30508. ></DIV
  30509. ><DIV
  30510. CLASS="sect1"
  30511. ><HR><H2
  30512. CLASS="sect1"
  30513. ><A
  30514. NAME="language.oop.serialization"
  30515. >Serializing objects - objects in sessions</A
  30516. ></H2
  30517. ><DIV
  30518. CLASS="note"
  30519. ><BLOCKQUOTE
  30520. CLASS="note"
  30521. ><P
  30522. ><B
  30523. >Note: </B
  30524. >
  30525.     In PHP 3, objects will lose their class association
  30526.     throughout the process of serialization and unserialization. 
  30527.     The resulting variable is of type object, but has no class
  30528.     and no methods, thus it is pretty useless (it has become
  30529.     just like an array with a funny syntax).
  30530.    </P
  30531. ></BLOCKQUOTE
  30532. ></DIV
  30533. ><DIV
  30534. CLASS="caution"
  30535. ><P
  30536. ></P
  30537. ><TABLE
  30538. CLASS="caution"
  30539. BORDER="1"
  30540. WIDTH="100%"
  30541. ><TR
  30542. ><TD
  30543. ALIGN="CENTER"
  30544. ><B
  30545. >Caution</B
  30546. ></TD
  30547. ></TR
  30548. ><TR
  30549. ><TD
  30550. ALIGN="LEFT"
  30551. ><P
  30552. >     The following information is valid for PHP 4 only. 
  30553.    </P
  30554. ></TD
  30555. ></TR
  30556. ></TABLE
  30557. ></DIV
  30558. ><P
  30559. >    <A
  30560. HREF="#function.serialize"
  30561. ><B
  30562. CLASS="function"
  30563. >serialize()</B
  30564. ></A
  30565. > returns a string containing a
  30566.    byte-stream representation of any value that can be stored in
  30567.    PHP. <A
  30568. HREF="#function.unserialize"
  30569. ><B
  30570. CLASS="function"
  30571. >unserialize()</B
  30572. ></A
  30573. > can use this string to
  30574.    recreate the original variable values. Using serialize to
  30575.    save an object will save all variables in an object.  The
  30576.    functions in an object will not be saved, only the name of
  30577.    the class.
  30578.   </P
  30579. ><P
  30580. >    In order to be able to <A
  30581. HREF="#function.unserialize"
  30582. ><B
  30583. CLASS="function"
  30584. >unserialize()</B
  30585. ></A
  30586. > an object, the
  30587.    class of that object needs to be defined. That is, if you have an object
  30588.    <VAR
  30589. CLASS="varname"
  30590. >$a</VAR
  30591. > of class A on page1.php and serialize this, you'll
  30592.    get a string that refers to class A and contains all values of variabled
  30593.    contained in <VAR
  30594. CLASS="varname"
  30595. >$a</VAR
  30596. >. If you want to be able to unserialize
  30597.    this on page2.php, recreating <VAR
  30598. CLASS="varname"
  30599. >$a</VAR
  30600. > of class A, the
  30601.    definition of class A must be present in page2.php. This can be done for
  30602.    example by storing the class definition of class A in an include file and
  30603.    including this file in both page1.php and page2.php.
  30604.   </P
  30605. ><DIV
  30606. CLASS="informalexample"
  30607. ><P
  30608. ></P
  30609. ><A
  30610. NAME="AEN5307"
  30611. ></A
  30612. ><TABLE
  30613. BORDER="0"
  30614. BGCOLOR="#E0E0E0"
  30615. CELLPADDING="5"
  30616. ><TR
  30617. ><TD
  30618. ><PRE
  30619. CLASS="php"
  30620. ><?php
  30621. // classa.inc:
  30622.   
  30623.   class A {
  30624.       var $one = 1;
  30625.     
  30626.       function show_one() {
  30627.           echo $this->one;
  30628.       }
  30629.   }
  30630.   
  30631. // page1.php:
  30632.  
  30633.   include("classa.inc");
  30634.   
  30635.   $a = new A;
  30636.   $s = serialize($a);
  30637.   // store $s somewhere where page2.php can find it.
  30638.   $fp = fopen("store", "w");
  30639.   fwrite($fp, $s);
  30640.   fclose($fp);
  30641.  
  30642. // page2.php:
  30643.   
  30644.   // this is needed for the unserialize to work properly.
  30645.   include("classa.inc");
  30646.  
  30647.   $s = implode("", @file("store"));
  30648.   $a = unserialize($s);
  30649.  
  30650.   // now use the function show_one() of the $a object.  
  30651.   $a->show_one();
  30652. ?></PRE
  30653. ></TD
  30654. ></TR
  30655. ></TABLE
  30656. ><P
  30657. ></P
  30658. ></DIV
  30659. ><P
  30660. >    If you are using sessions and use <A
  30661. HREF="#function.session-register"
  30662. ><B
  30663. CLASS="function"
  30664. >session_register()</B
  30665. ></A
  30666. >
  30667.    to register objects, these objects are serialized automatically
  30668.    at the end of each PHP page, and are unserialized automatically on
  30669.    each of the following pages. This basically means that these objects
  30670.    can show up on any of your pages once they become part of your
  30671.    session.
  30672.   </P
  30673. ><P
  30674. >    It is strongly recommended that you include the class
  30675.    definitions of all such registered objects on all of your
  30676.    pages, even if you do not actually use these classes on all
  30677.    of your pages. If you don't and an object is being
  30678.    unserialized without its class definition being present, it
  30679.    will lose its class association and become an object of class
  30680.    <VAR
  30681. CLASS="literal"
  30682. >stdClass</VAR
  30683. > without any functions available
  30684.    at all, that is, it will become quite useless.
  30685.   </P
  30686. ><P
  30687. >    So if in the example above <VAR
  30688. CLASS="varname"
  30689. >$a</VAR
  30690. > became part of a session
  30691.    by running <VAR
  30692. CLASS="literal"
  30693. >session_register("a")</VAR
  30694. >, you should include the
  30695.    file <VAR
  30696. CLASS="literal"
  30697. >classa.inc</VAR
  30698. > on all of your pages, not only page1.php
  30699.    and page2.php.
  30700.   </P
  30701. ></DIV
  30702. ><DIV
  30703. CLASS="sect1"
  30704. ><HR><H2
  30705. CLASS="sect1"
  30706. ><A
  30707. NAME="language.oop.magic-functions"
  30708. >The magic functions <VAR
  30709. CLASS="literal"
  30710. >__sleep</VAR
  30711. > and <VAR
  30712. CLASS="literal"
  30713. >__wakeup</VAR
  30714. ></A
  30715. ></H2
  30716. ><P
  30717. >    <A
  30718. HREF="#function.serialize"
  30719. ><B
  30720. CLASS="function"
  30721. >serialize()</B
  30722. ></A
  30723. > checks if your class has a function with
  30724.    the magic name <VAR
  30725. CLASS="literal"
  30726. >__sleep</VAR
  30727. >. If so, that function is
  30728.    being run prior to any serialization. It can clean up the object
  30729.    and is supposed to return an array with the names of all variables
  30730.    of that object that should be serialized.
  30731.   </P
  30732. ><P
  30733. >    The intended use of <VAR
  30734. CLASS="literal"
  30735. >__sleep</VAR
  30736. > is to close any
  30737.    database connections that object may have, committing pending
  30738.    data or perform similar cleanup tasks. Also, the function is
  30739.    useful if you have very large objects which need not be
  30740.    saved completely.
  30741.   </P
  30742. ><P
  30743. >    Conversely, <A
  30744. HREF="#function.unserialize"
  30745. ><B
  30746. CLASS="function"
  30747. >unserialize()</B
  30748. ></A
  30749. > checks for the
  30750.    presence of a function with the magic name 
  30751.    <VAR
  30752. CLASS="literal"
  30753. >__wakeup</VAR
  30754. >. If present, this function can
  30755.    reconstruct any resources that object may have.
  30756.   </P
  30757. ><P
  30758. >     The intended use of <VAR
  30759. CLASS="literal"
  30760. >__wakeup</VAR
  30761. > is to
  30762.     reestablish any database connections that may have been lost
  30763.     during serialization and perform other reinitialization
  30764.     tasks.
  30765.   </P
  30766. ></DIV
  30767. ><DIV
  30768. CLASS="sect1"
  30769. ><HR><H2
  30770. CLASS="sect1"
  30771. ><A
  30772. NAME="language.oop.newref"
  30773. >References inside the constructor</A
  30774. ></H2
  30775. ><P
  30776. >     Creating references within the constructor can lead to confusing
  30777.     results. This tutorial-like section helps you to avoid problems.
  30778.  
  30779.     <DIV
  30780. CLASS="informalexample"
  30781. ><P
  30782. ></P
  30783. ><A
  30784. NAME="AEN5334"
  30785. ></A
  30786. ><TABLE
  30787. BORDER="0"
  30788. BGCOLOR="#E0E0E0"
  30789. CELLPADDING="5"
  30790. ><TR
  30791. ><TD
  30792. ><PRE
  30793. CLASS="php"
  30794. ><?php
  30795. class Foo {
  30796.     function Foo($name) {
  30797.         // create a reference inside the global array $globalref
  30798.         global $globalref;
  30799.         $globalref[] = &$this;
  30800.         // set name to passed value
  30801.         $this->setName($name);
  30802.         // and put it out
  30803.         $this->echoName();
  30804.     }
  30805.  
  30806.     function echoName() {
  30807.         echo "<br />", $this->name;
  30808.     }
  30809.  
  30810.     function setName($name) {
  30811.         $this->name = $name;
  30812.     }
  30813. }
  30814. ?></PRE
  30815. ></TD
  30816. ></TR
  30817. ></TABLE
  30818. ><P
  30819. ></P
  30820. ></DIV
  30821. >
  30822.   </P
  30823. ><P
  30824. >     Let us check out if there is a difference between
  30825.     <VAR
  30826. CLASS="varname"
  30827. >$bar1</VAR
  30828. > which has been created using
  30829.     the copy <VAR
  30830. CLASS="literal"
  30831. >=</VAR
  30832. > operator and
  30833.     <VAR
  30834. CLASS="varname"
  30835. >$bar2</VAR
  30836. > which has been created using
  30837.     the reference <VAR
  30838. CLASS="literal"
  30839. >=&</VAR
  30840. > operator...
  30841.  
  30842.     <DIV
  30843. CLASS="informalexample"
  30844. ><P
  30845. ></P
  30846. ><A
  30847. NAME="AEN5341"
  30848. ></A
  30849. ><TABLE
  30850. BORDER="0"
  30851. BGCOLOR="#E0E0E0"
  30852. CELLPADDING="5"
  30853. ><TR
  30854. ><TD
  30855. ><PRE
  30856. CLASS="php"
  30857. ><?php
  30858. $bar1 = new Foo('set in constructor');
  30859. $bar1->echoName();
  30860. $globalref[0]->echoName();
  30861.  
  30862. /* output:
  30863. set in constructor
  30864. set in constructor
  30865. set in constructor */
  30866.  
  30867. $bar2 =& new Foo('set in constructor');
  30868. $bar2->echoName();
  30869. $globalref[1]->echoName();
  30870.  
  30871. /* output:
  30872. set in constructor
  30873. set in constructor
  30874. set in constructor */
  30875. ?></PRE
  30876. ></TD
  30877. ></TR
  30878. ></TABLE
  30879. ><P
  30880. ></P
  30881. ></DIV
  30882. >
  30883.    </P
  30884. ><P
  30885. >     Apparently there is no difference, but in fact there is a
  30886.     very significant one: <VAR
  30887. CLASS="varname"
  30888. >$bar1</VAR
  30889. > and
  30890.     <VAR
  30891. CLASS="varname"
  30892. >$globalref[0]</VAR
  30893. > are _NOT_ referenced, they
  30894.     are NOT the same variable. This is because "new" does not
  30895.     return a reference by default, instead it returns a copy.
  30896.     <DIV
  30897. CLASS="note"
  30898. ><BLOCKQUOTE
  30899. CLASS="note"
  30900. ><P
  30901. ><B
  30902. >Note: </B
  30903. >
  30904.       There is no performance loss (since PHP 4 and up use reference
  30905.       counting) returning copies instead of references. On the
  30906.       contrary it is most often better to simply work with copies
  30907.       instead of references, because creating references takes some
  30908.       time where creating copies virtually takes no time (unless none
  30909.       of them is a large array or object and one of them gets changed
  30910.       and the other(s) one(s) subsequently, then it would be wise to
  30911.       use references to change them all concurrently).
  30912.      </P
  30913. ></BLOCKQUOTE
  30914. ></DIV
  30915. >
  30916.     To prove what is written above let us watch the code below.
  30917.  
  30918.     <DIV
  30919. CLASS="informalexample"
  30920. ><P
  30921. ></P
  30922. ><A
  30923. NAME="AEN5348"
  30924. ></A
  30925. ><TABLE
  30926. BORDER="0"
  30927. BGCOLOR="#E0E0E0"
  30928. CELLPADDING="5"
  30929. ><TR
  30930. ><TD
  30931. ><PRE
  30932. CLASS="php"
  30933. ><?php
  30934. // now we will change the name. what do you expect?
  30935. // you could expect that both $bar1 and $globalref[0] change their names...
  30936. $bar1->setName('set from outside');
  30937.  
  30938. // as mentioned before this is not the case.
  30939. $bar1->echoName();
  30940. $globalref[0]->echoName();
  30941.  
  30942. /* output:
  30943. set from outside
  30944. set in constructor */
  30945.  
  30946. // let us see what is different with $bar2 and $globalref[1]
  30947. $bar2->setName('set from outside');
  30948.  
  30949. // luckily they are not only equal, they are the same variable
  30950. // thus $bar2->name and $globalref[1]->name are the same too
  30951. $bar2->echoName();
  30952. $globalref[1]->echoName();
  30953.  
  30954. /* output:
  30955. set from outside
  30956. set from outside */
  30957. ?></PRE
  30958. ></TD
  30959. ></TR
  30960. ></TABLE
  30961. ><P
  30962. ></P
  30963. ></DIV
  30964. >   
  30965.    </P
  30966. ><P
  30967. >    Another final example, try to understand it.
  30968.    
  30969.     <DIV
  30970. CLASS="informalexample"
  30971. ><P
  30972. ></P
  30973. ><A
  30974. NAME="AEN5351"
  30975. ></A
  30976. ><TABLE
  30977. BORDER="0"
  30978. BGCOLOR="#E0E0E0"
  30979. CELLPADDING="5"
  30980. ><TR
  30981. ><TD
  30982. ><PRE
  30983. CLASS="php"
  30984. ><?php
  30985. class A {
  30986.     function A($i) {
  30987.         $this->value = $i;
  30988.         // try to figure out why we do not need a reference here
  30989.         $this->b = new B($this);
  30990.     }
  30991.  
  30992.     function createRef() {
  30993.         $this->c = new B($this);
  30994.     }
  30995.  
  30996.     function echoValue() {
  30997.         echo "<br />","class ",get_class($this),': ',$this->value;
  30998.     }
  30999. }
  31000.  
  31001.  
  31002. class B {
  31003.     function B(&$a) {
  31004.         $this->a = &$a;
  31005.     }
  31006.  
  31007.     function echoValue() {
  31008.         echo "<br />","class ",get_class($this),': ',$this->a->value;
  31009.     }
  31010. }
  31011.  
  31012. // try to understand why using a simple copy here would yield
  31013. // in an undesired result in the *-marked line
  31014. $a =& new A(10);
  31015. $a->createRef();
  31016.  
  31017. $a->echoValue();
  31018. $a->b->echoValue();
  31019. $a->c->echoValue();
  31020.  
  31021. $a->value = 11;
  31022.  
  31023. $a->echoValue();
  31024. $a->b->echoValue(); // *
  31025. $a->c->echoValue();
  31026.  
  31027. ?></PRE
  31028. ></TD
  31029. ></TR
  31030. ></TABLE
  31031. ><P
  31032. >       This example will output:
  31033.      </P
  31034. ><TABLE
  31035. BORDER="0"
  31036. BGCOLOR="#E0E0E0"
  31037. CELLPADDING="5"
  31038. ><TR
  31039. ><TD
  31040. ><PRE
  31041. CLASS="screen"
  31042. >class A: 10
  31043. class B: 10
  31044. class B: 10
  31045. class A: 11
  31046. class B: 11
  31047. class B: 11</PRE
  31048. ></TD
  31049. ></TR
  31050. ></TABLE
  31051. ><P
  31052. ></P
  31053. ></DIV
  31054. >
  31055.    </P
  31056. ></DIV
  31057. ><DIV
  31058. CLASS="sect1"
  31059. ><HR><H2
  31060. CLASS="sect1"
  31061. ><A
  31062. NAME="language.oop.object-comparison"
  31063. >Comparing objects</A
  31064. ></H2
  31065. ><P
  31066. >    In PHP 4, objects are compared in a very simple manner, namely: Two object
  31067.    instances are equal if they have the same attributes and values, and are
  31068.    instances of the same class. Similar rules are applied when comparing two
  31069.    objects using the identity operator (<VAR
  31070. CLASS="literal"
  31071. >===</VAR
  31072. >).
  31073.   </P
  31074. ><P
  31075. >    If we were to execute the code in the example below:
  31076.    <TABLE
  31077. WIDTH="100%"
  31078. BORDER="0"
  31079. CELLPADDING="0"
  31080. CELLSPACING="0"
  31081. CLASS="EXAMPLE"
  31082. ><TR
  31083. ><TD
  31084. ><DIV
  31085. CLASS="example"
  31086. ><A
  31087. NAME="AEN5360"
  31088. ></A
  31089. ><P
  31090. ><B
  31091. >Example 18-1. Example of object comparison in PHP 4</B
  31092. ></P
  31093. ><TABLE
  31094. BORDER="0"
  31095. BGCOLOR="#E0E0E0"
  31096. CELLPADDING="5"
  31097. ><TR
  31098. ><TD
  31099. ><PRE
  31100. CLASS="php"
  31101. ><?php
  31102. function bool2str($bool) {
  31103.     if ($bool === false) {
  31104.             return 'FALSE';
  31105.     } else {
  31106.             return 'TRUE';
  31107.     }
  31108. }
  31109.  
  31110. function compareObjects(&$o1, &$o2) {
  31111.     echo 'o1 == o2 : '.bool2str($o1 == $o2)."\n";
  31112.     echo 'o1 != o2 : '.bool2str($o1 != $o2)."\n";
  31113.     echo 'o1 === o2 : '.bool2str($o1 === $o2)."\n";
  31114.     echo 'o1 !== o2 : '.bool2str($o1 !== $o2)."\n";
  31115. }
  31116.  
  31117. class Flag {
  31118.     var $flag;
  31119.  
  31120.     function Flag($flag=true) {
  31121.             $this->flag = $flag;
  31122.     }
  31123. }
  31124.  
  31125. class SwitchableFlag extends Flag {
  31126.  
  31127.     function turnOn() {
  31128.         $this->flag = true;
  31129.     }
  31130.  
  31131.     function turnOff() {
  31132.         $this->flag = false;
  31133.     }
  31134. }
  31135.  
  31136. $o = new Flag();
  31137. $p = new Flag(false);
  31138. $q = new Flag();
  31139.  
  31140. $r = new SwitchableFlag();
  31141.  
  31142. echo "Compare instances created with the same parameters\n";
  31143. compareObjects($o, $q);
  31144.  
  31145. echo "\nCompare instances created with different parameters\n";
  31146. compareObjects($o, $p);
  31147.  
  31148. echo "\nCompare an instance of a parent class with one from a subclass\n";
  31149. compareObjects($o, $r);
  31150. ?></PRE
  31151. ></TD
  31152. ></TR
  31153. ></TABLE
  31154. ></DIV
  31155. ></TD
  31156. ></TR
  31157. ></TABLE
  31158. >
  31159.    We will see:
  31160.    <TABLE
  31161. BORDER="0"
  31162. BGCOLOR="#E0E0E0"
  31163. CELLPADDING="5"
  31164. ><TR
  31165. ><TD
  31166. ><PRE
  31167. CLASS="screen"
  31168. >Compare instances created with the same parameters
  31169. o1 == o2 : TRUE
  31170. o1 != o2 : FALSE
  31171. o1 === o2 : TRUE
  31172. o1 !== o2 : FALSE
  31173.  
  31174. Compare instances created with different parameters
  31175. o1 == o2 : FALSE
  31176. o1 != o2 : TRUE
  31177. o1 === o2 : FALSE
  31178. o1 !== o2 : TRUE
  31179.  
  31180. Compare an instance of a parent class with one from a subclass
  31181. o1 == o2 : FALSE
  31182. o1 != o2 : TRUE
  31183. o1 === o2 : FALSE
  31184. o1 !== o2 : TRUE</PRE
  31185. ></TD
  31186. ></TR
  31187. ></TABLE
  31188. >
  31189.    Which is the output we will expect to obtain given the comparison rules
  31190.    above. Only instances with the same values for their attributes and from the same
  31191.    class are considered equal and identical.
  31192.   </P
  31193. ><P
  31194. >    Even in the cases where we have object composition, the same comparison
  31195.    rules apply. In the example below we create a container class that stores
  31196.    an associative array of <B
  31197. CLASS="classname"
  31198. >Flag</B
  31199. > objects.
  31200.    <TABLE
  31201. WIDTH="100%"
  31202. BORDER="0"
  31203. CELLPADDING="0"
  31204. CELLSPACING="0"
  31205. CLASS="EXAMPLE"
  31206. ><TR
  31207. ><TD
  31208. ><DIV
  31209. CLASS="example"
  31210. ><A
  31211. NAME="AEN5366"
  31212. ></A
  31213. ><P
  31214. ><B
  31215. >Example 18-2. Compound object comparisons in PHP 4</B
  31216. ></P
  31217. ><TABLE
  31218. BORDER="0"
  31219. BGCOLOR="#E0E0E0"
  31220. CELLPADDING="5"
  31221. ><TR
  31222. ><TD
  31223. ><PRE
  31224. CLASS="php"
  31225. ><?php
  31226. class FlagSet {
  31227.     var $set;
  31228.  
  31229.     function FlagSet($flagArr = array()) {
  31230.         $this->set = $flagArr;
  31231.     }
  31232.  
  31233.     function addFlag($name, $flag) {
  31234.         $this->set[$name] = $flag;
  31235.     }
  31236.  
  31237.     function removeFlag($name) {
  31238.         if (array_key_exists($name, $this->set)) {
  31239.             unset($this->set[$name]);
  31240.         }
  31241.     }
  31242. }
  31243.  
  31244.  
  31245. $u = new FlagSet();
  31246. $u->addFlag('flag1', $o);
  31247. $u->addFlag('flag2', $p);
  31248. $v = new FlagSet(array('flag1'=>$q, 'flag2'=>$p));
  31249. $w = new FlagSet(array('flag1'=>$q));
  31250.  
  31251. echo "\nComposite objects u(o,p) and v(q,p)\n";
  31252. compareObjects($u, $v);
  31253.  
  31254. echo "\nu(o,p) and w(q)\n";
  31255. compareObjects($u, $w);
  31256. ?></PRE
  31257. ></TD
  31258. ></TR
  31259. ></TABLE
  31260. ></DIV
  31261. ></TD
  31262. ></TR
  31263. ></TABLE
  31264. >
  31265.    Which gives the expected output:
  31266.    <TABLE
  31267. BORDER="0"
  31268. BGCOLOR="#E0E0E0"
  31269. CELLPADDING="5"
  31270. ><TR
  31271. ><TD
  31272. ><PRE
  31273. CLASS="screen"
  31274. >Composite objects u(o,p) and v(q,p)
  31275. o1 == o2 : TRUE
  31276. o1 != o2 : FALSE
  31277. o1 === o2 : TRUE
  31278. o1 !== o2 : FALSE
  31279.  
  31280. u(o,p) and w(q)
  31281. o1 == o2 : FALSE
  31282. o1 != o2 : TRUE
  31283. o1 === o2 : FALSE
  31284. o1 !== o2 : TRUE</PRE
  31285. ></TD
  31286. ></TR
  31287. ></TABLE
  31288. >
  31289.   </P
  31290. ></DIV
  31291. ></DIV
  31292. ><DIV
  31293. CLASS="chapter"
  31294. ><HR><H1
  31295. ><A
  31296. NAME="language.oop5"
  31297. >Chapter 19. Classes and Objects (PHP 5)</A
  31298. ></H1
  31299. ><DIV
  31300. CLASS="sect1"
  31301. ><H2
  31302. CLASS="sect1"
  31303. ><A
  31304. NAME="op5.intro"
  31305. >Introduction</A
  31306. ></H2
  31307. ><P
  31308. >     In PHP 5 there is a new Object Model. PHP's handling of objects has been
  31309.     completely rewritten, allowing for better performance and more features.
  31310.    </P
  31311. ></DIV
  31312. ><DIV
  31313. CLASS="sect1"
  31314. ><HR><H2
  31315. CLASS="sect1"
  31316. ><A
  31317. NAME="language.oop5.basic"
  31318. >The Basics</A
  31319. ></H2
  31320. ><DIV
  31321. CLASS="sect2"
  31322. ><H3
  31323. CLASS="sect2"
  31324. ><A
  31325. NAME="language.oop5.basic.class"
  31326. >class</A
  31327. ></H3
  31328. ><P
  31329. >     Every class definition begins with the keyword class, followed by a class
  31330.     name, which can be any name that isn't a <A
  31331. HREF="#reserved"
  31332. >reserved</A
  31333. >
  31334.     word in PHP. Followed  by a pair of curly braces, of
  31335.     which contains the definition of the classes members and methods. Within
  31336.     each method, except for <A
  31337. HREF="#language.oop5.static"
  31338. >static</A
  31339. >
  31340.     methods, a pseudo variable <VAR
  31341. CLASS="varname"
  31342. >$this</VAR
  31343. > is available.
  31344.     <VAR
  31345. CLASS="varname"
  31346. >$this</VAR
  31347. > is a reference to the same instance that
  31348.     called the method.
  31349.    </P
  31350. ><TABLE
  31351. WIDTH="100%"
  31352. BORDER="0"
  31353. CELLPADDING="0"
  31354. CELLSPACING="0"
  31355. CLASS="EXAMPLE"
  31356. ><TR
  31357. ><TD
  31358. ><DIV
  31359. CLASS="example"
  31360. ><A
  31361. NAME="AEN5384"
  31362. ></A
  31363. ><P
  31364. ><B
  31365. >Example 19-1. Simple Class definition</B
  31366. ></P
  31367. ><TABLE
  31368. BORDER="0"
  31369. BGCOLOR="#E0E0E0"
  31370. CELLPADDING="5"
  31371. ><TR
  31372. ><TD
  31373. ><PRE
  31374. CLASS="php"
  31375. ><?php
  31376. class SimpleClass
  31377. {
  31378.     // member declaration
  31379.     public $var = 'a default value';
  31380.  
  31381.     // method declaration
  31382.     public function displayVar() {
  31383.         echo $this->var;
  31384.     }
  31385. }
  31386. ?></PRE
  31387. ></TD
  31388. ></TR
  31389. ></TABLE
  31390. ></DIV
  31391. ></TD
  31392. ></TR
  31393. ></TABLE
  31394. ></DIV
  31395. ><DIV
  31396. CLASS="sect2"
  31397. ><HR><H3
  31398. CLASS="sect2"
  31399. ><A
  31400. NAME="language.oop5.basic.new"
  31401. >new</A
  31402. ></H3
  31403. ><P
  31404. >     To create an instance of an object, a new object must be created and
  31405.     assigned to a variable.  An object will always be assigned when
  31406.     creating a new object unless the object has a
  31407.     <A
  31408. HREF="#language.oop5.decon"
  31409. >constructor</A
  31410. > defined that throws an
  31411.     <A
  31412. HREF="#language.exceptions"
  31413. >exception</A
  31414. > on error.
  31415.    </P
  31416. ><TABLE
  31417. WIDTH="100%"
  31418. BORDER="0"
  31419. CELLPADDING="0"
  31420. CELLSPACING="0"
  31421. CLASS="EXAMPLE"
  31422. ><TR
  31423. ><TD
  31424. ><DIV
  31425. CLASS="example"
  31426. ><A
  31427. NAME="AEN5392"
  31428. ></A
  31429. ><P
  31430. ><B
  31431. >Example 19-2. Creating an instance</B
  31432. ></P
  31433. ><TABLE
  31434. BORDER="0"
  31435. BGCOLOR="#E0E0E0"
  31436. CELLPADDING="5"
  31437. ><TR
  31438. ><TD
  31439. ><PRE
  31440. CLASS="php"
  31441. ><?php
  31442. $instance = new SimpleClass()
  31443. ?></PRE
  31444. ></TD
  31445. ></TR
  31446. ></TABLE
  31447. ></DIV
  31448. ></TD
  31449. ></TR
  31450. ></TABLE
  31451. ><P
  31452. >     When assigning an already created instance of an object to a new variable, the new variable
  31453.     will access the same instance as the object that was assigned. This
  31454.     behaviour is the same when passing instances to a function. A new instance
  31455.     of an already created object can be made by
  31456.     <A
  31457. HREF="#language.oop5.cloning"
  31458. >cloning</A
  31459. > it.
  31460.    </P
  31461. ><TABLE
  31462. WIDTH="100%"
  31463. BORDER="0"
  31464. CELLPADDING="0"
  31465. CELLSPACING="0"
  31466. CLASS="EXAMPLE"
  31467. ><TR
  31468. ><TD
  31469. ><DIV
  31470. CLASS="example"
  31471. ><A
  31472. NAME="AEN5397"
  31473. ></A
  31474. ><P
  31475. ><B
  31476. >Example 19-3. Object Assignment</B
  31477. ></P
  31478. ><TABLE
  31479. BORDER="0"
  31480. BGCOLOR="#E0E0E0"
  31481. CELLPADDING="5"
  31482. ><TR
  31483. ><TD
  31484. ><PRE
  31485. CLASS="php"
  31486. ><?php
  31487. $assigned   =  $instance;
  31488. $reference  =& $instance;
  31489.  
  31490. $instance->var = '$assigned will have this value';
  31491.  
  31492. $instance = null; // $instance and $reference become null
  31493.  
  31494. var_dump($instance);
  31495. var_dump($reference);
  31496. var_dump($assigned);
  31497. ?></PRE
  31498. ></TD
  31499. ></TR
  31500. ></TABLE
  31501. ><P
  31502. >The above example will output:</P
  31503. ><TABLE
  31504. BORDER="0"
  31505. BGCOLOR="#E0E0E0"
  31506. CELLPADDING="5"
  31507. ><TR
  31508. ><TD
  31509. ><PRE
  31510. CLASS="screen"
  31511. >NULL
  31512. NULL
  31513. object(SimpleClass)#1 (1) {
  31514.    ["var"]=>
  31515.      string(30) "$assigned will have this value"
  31516. }</PRE
  31517. ></TD
  31518. ></TR
  31519. ></TABLE
  31520. ></DIV
  31521. ></TD
  31522. ></TR
  31523. ></TABLE
  31524. ></DIV
  31525. ><DIV
  31526. CLASS="sect2"
  31527. ><HR><H3
  31528. CLASS="sect2"
  31529. ><A
  31530. NAME="language.oop5.basic.extends"
  31531. >extends</A
  31532. ></H3
  31533. ><P
  31534. >     A class can inherit methods and members of another class by using the
  31535.     extends keyword in the declaration. It is not possible to extend multiple
  31536.     classes, a class can only inherit one base class.
  31537.    </P
  31538. ><P
  31539. >     The inherited methods and members can be overrided, unless the parent
  31540.     class has defined a method as <A
  31541. HREF="#language.oop5.final"
  31542. >final</A
  31543. >,
  31544.     by redeclaring them within the same name defined in the parent class.
  31545.     It is possible to access the overrided method or members by
  31546.     referencing them with <A
  31547. HREF="#language.oop5.paamayim-nekudotayim"
  31548. >parent::</A
  31549. >
  31550.    </P
  31551. ><TABLE
  31552. WIDTH="100%"
  31553. BORDER="0"
  31554. CELLPADDING="0"
  31555. CELLSPACING="0"
  31556. CLASS="EXAMPLE"
  31557. ><TR
  31558. ><TD
  31559. ><DIV
  31560. CLASS="example"
  31561. ><A
  31562. NAME="AEN5408"
  31563. ></A
  31564. ><P
  31565. ><B
  31566. >Example 19-4. Simple Class Inherintance</B
  31567. ></P
  31568. ><TABLE
  31569. BORDER="0"
  31570. BGCOLOR="#E0E0E0"
  31571. CELLPADDING="5"
  31572. ><TR
  31573. ><TD
  31574. ><PRE
  31575. CLASS="php"
  31576. ><?php
  31577. class ExtendClass extends SimpleClass
  31578. {
  31579.     // Redefine the parent method
  31580.     function displayVar()
  31581.     {
  31582.         echo "Extending class\n";
  31583.         parent::displayVar();
  31584.     }
  31585. }
  31586.  
  31587. $extended = new ExtendClass();
  31588. $extended->displayVar();
  31589. ?></PRE
  31590. ></TD
  31591. ></TR
  31592. ></TABLE
  31593. ><P
  31594. >The above example will output:</P
  31595. ><TABLE
  31596. BORDER="0"
  31597. BGCOLOR="#E0E0E0"
  31598. CELLPADDING="5"
  31599. ><TR
  31600. ><TD
  31601. ><PRE
  31602. CLASS="screen"
  31603. >Extending class
  31604. a default value</PRE
  31605. ></TD
  31606. ></TR
  31607. ></TABLE
  31608. ></DIV
  31609. ></TD
  31610. ></TR
  31611. ></TABLE
  31612. ></DIV
  31613. ></DIV
  31614. ><DIV
  31615. CLASS="sect1"
  31616. ><HR><H2
  31617. CLASS="sect1"
  31618. ><A
  31619. NAME="language.oop5.autoload"
  31620. >Autoloading Objects</A
  31621. ></H2
  31622. ><P
  31623. >    Many developers writing object-oriented applications create
  31624.    one PHP source file per-class definition. One of the biggest
  31625.    annoyances is having to write a long list of needed includes
  31626.    at the beginning of each script (one for each class).
  31627.   </P
  31628. ><P
  31629. >    In PHP 5, this is no longer necessary. You may define an
  31630.    __autoload function which is automatically
  31631.    called in case you are trying to use a class which hasn't been
  31632.    defined yet. By calling this function the scripting engine is given
  31633.    a last chance to load the class before PHP fails with an error.
  31634.   </P
  31635. ><DIV
  31636. CLASS="note"
  31637. ><BLOCKQUOTE
  31638. CLASS="note"
  31639. ><P
  31640. ><B
  31641. >Note: </B
  31642. >
  31643.     Exceptions thrown in __autoload function cannot be catched in the
  31644.     <A
  31645. HREF="#language.exceptions"
  31646. >catch</A
  31647. > block and result in fatal
  31648.     error.
  31649.    </P
  31650. ></BLOCKQUOTE
  31651. ></DIV
  31652. ><P
  31653. >    <TABLE
  31654. WIDTH="100%"
  31655. BORDER="0"
  31656. CELLPADDING="0"
  31657. CELLSPACING="0"
  31658. CLASS="EXAMPLE"
  31659. ><TR
  31660. ><TD
  31661. ><DIV
  31662. CLASS="example"
  31663. ><A
  31664. NAME="AEN5421"
  31665. ></A
  31666. ><P
  31667. ><B
  31668. >Example 19-5. Autoload example</B
  31669. ></P
  31670. ><P
  31671. >      This example attempts to load the classes <VAR
  31672. CLASS="literal"
  31673. >MyClass1</VAR
  31674. >
  31675.      and <VAR
  31676. CLASS="literal"
  31677. >MyClass2</VAR
  31678. > from the files <TT
  31679. CLASS="filename"
  31680. >MyClass1.php</TT
  31681. >
  31682.      and <TT
  31683. CLASS="filename"
  31684. >MyClass2.php</TT
  31685. > respectively.
  31686.     </P
  31687. ><TABLE
  31688. BORDER="0"
  31689. BGCOLOR="#E0E0E0"
  31690. CELLPADDING="5"
  31691. ><TR
  31692. ><TD
  31693. ><PRE
  31694. CLASS="php"
  31695. ><?php
  31696. function __autoload($class_name) {
  31697.     require_once $class_name . '.php';
  31698. }
  31699.  
  31700. $obj  = new MyClass1();
  31701. $obj2 = new MyClass2(); 
  31702. ?></PRE
  31703. ></TD
  31704. ></TR
  31705. ></TABLE
  31706. ></DIV
  31707. ></TD
  31708. ></TR
  31709. ></TABLE
  31710. >
  31711.   </P
  31712. ></DIV
  31713. ><DIV
  31714. CLASS="sect1"
  31715. ><HR><H2
  31716. CLASS="sect1"
  31717. ><A
  31718. NAME="language.oop5.decon"
  31719. >Constructors and Destructors</A
  31720. ></H2
  31721. ><DIV
  31722. CLASS="sect2"
  31723. ><H3
  31724. CLASS="sect2"
  31725. ><A
  31726. NAME="language.oop5.decon.constructor"
  31727. >Constructor</A
  31728. ></H3
  31729. >void <B
  31730. CLASS="methodname"
  31731. >__construct</B
  31732. > ( [mixed args [, ...]])<BR
  31733. ></BR
  31734. ><P
  31735. >     PHP 5 allows developers to declare constructor methods for classes.
  31736.     Classes which have a constructor method call this method on each
  31737.     newly-created object, so it is suitable for any initialization that the
  31738.     object may need before it is used.
  31739.    </P
  31740. ><DIV
  31741. CLASS="note"
  31742. ><BLOCKQUOTE
  31743. CLASS="note"
  31744. ><P
  31745. ><B
  31746. >Note: </B
  31747. >
  31748.      Parent constructors are not called implicitly if the child class defines
  31749.      a constructor.  In order to run a parent constructor, a call to
  31750.      <B
  31751. CLASS="function"
  31752. >parent::__construct()</B
  31753. > within the child constructor is
  31754.      required.
  31755.     </P
  31756. ></BLOCKQUOTE
  31757. ></DIV
  31758. ><TABLE
  31759. WIDTH="100%"
  31760. BORDER="0"
  31761. CELLPADDING="0"
  31762. CELLSPACING="0"
  31763. CLASS="EXAMPLE"
  31764. ><TR
  31765. ><TD
  31766. ><DIV
  31767. CLASS="example"
  31768. ><A
  31769. NAME="AEN5445"
  31770. ></A
  31771. ><P
  31772. ><B
  31773. >Example 19-6. using new unified constructors</B
  31774. ></P
  31775. ><TABLE
  31776. BORDER="0"
  31777. BGCOLOR="#E0E0E0"
  31778. CELLPADDING="5"
  31779. ><TR
  31780. ><TD
  31781. ><PRE
  31782. CLASS="php"
  31783. ><?php
  31784. class BaseClass {
  31785.    function __construct() {
  31786.        print "In BaseClass constructor\n";
  31787.    }
  31788. }
  31789.  
  31790. class SubClass extends BaseClass {
  31791.    function __construct() {
  31792.        parent::__construct();
  31793.        print "In SubClass constructor\n";
  31794.    }
  31795. }
  31796.  
  31797. $obj = new BaseClass();
  31798. $obj = new SubClass();
  31799. ?></PRE
  31800. ></TD
  31801. ></TR
  31802. ></TABLE
  31803. ></DIV
  31804. ></TD
  31805. ></TR
  31806. ></TABLE
  31807. ><P
  31808. >     For backwards compatibility, if PHP 5 cannot find a 
  31809.     <B
  31810. CLASS="function"
  31811. >__construct()</B
  31812. > function for a given class, it will
  31813.     search for the old-style constructor function, by the name of the class.
  31814.     Effectively, it means that the only case that would have compatibility
  31815.     issues is if the class had a method named 
  31816.     <B
  31817. CLASS="function"
  31818. >__construct()</B
  31819. > which was used for different semantics.
  31820.    </P
  31821. ></DIV
  31822. ><DIV
  31823. CLASS="sect2"
  31824. ><HR><H3
  31825. CLASS="sect2"
  31826. ><A
  31827. NAME="language.oop5.decon.destructor"
  31828. >Destructor</A
  31829. ></H3
  31830. >void <B
  31831. CLASS="methodname"
  31832. >__destruct</B
  31833. > ( void )<BR
  31834. ></BR
  31835. ><P
  31836. >     PHP 5 introduces a destructor concept similar to that of other
  31837.     object-oriented languages, such as C++. The destructor method will be
  31838.     called as soon as all references to a particular object are removed or when
  31839.     the object is explicitly destroyed.
  31840.    </P
  31841. ><TABLE
  31842. WIDTH="100%"
  31843. BORDER="0"
  31844. CELLPADDING="0"
  31845. CELLSPACING="0"
  31846. CLASS="EXAMPLE"
  31847. ><TR
  31848. ><TD
  31849. ><DIV
  31850. CLASS="example"
  31851. ><A
  31852. NAME="AEN5458"
  31853. ></A
  31854. ><P
  31855. ><B
  31856. >Example 19-7. Destructor Example</B
  31857. ></P
  31858. ><TABLE
  31859. BORDER="0"
  31860. BGCOLOR="#E0E0E0"
  31861. CELLPADDING="5"
  31862. ><TR
  31863. ><TD
  31864. ><PRE
  31865. CLASS="php"
  31866. ><?php
  31867. class MyDestructableClass {
  31868.    function __construct() {
  31869.        print "In constructor\n";
  31870.        $this->name = "MyDestructableClass";
  31871.    }
  31872.  
  31873.    function __destruct() {
  31874.        print "Destroying " . $this->name . "\n";
  31875.    }
  31876. }
  31877.  
  31878. $obj = new MyDestructableClass();
  31879. ?></PRE
  31880. ></TD
  31881. ></TR
  31882. ></TABLE
  31883. ></DIV
  31884. ></TD
  31885. ></TR
  31886. ></TABLE
  31887. ><P
  31888. >     Like constructors, parent destructors will not be called implicitly by
  31889.     the engine. In order to run a parent destructor, one would have to
  31890.     explicitly call <B
  31891. CLASS="function"
  31892. >parent::__destruct()</B
  31893. > in the destructor
  31894.     body.
  31895.    </P
  31896. ></DIV
  31897. ></DIV
  31898. ><DIV
  31899. CLASS="sect1"
  31900. ><HR><H2
  31901. CLASS="sect1"
  31902. ><A
  31903. NAME="language.oop5.visibility"
  31904. >Visibility</A
  31905. ></H2
  31906. ><P
  31907. >    The visibility of a property or method can be defined by prefixing the
  31908.    declaration with the keywords: public, protected or private. Public
  31909.    declared items can be accessed everywhere. Protected limits access to
  31910.    inherited classes (and to the class that defines the item). Private limits
  31911.    visibility only to the class that defines the item.
  31912.   </P
  31913. ><DIV
  31914. CLASS="sect2"
  31915. ><HR><H3
  31916. CLASS="sect2"
  31917. ><A
  31918. NAME="language.oop5.visiblity-members"
  31919. >Members Visibility</A
  31920. ></H3
  31921. ><P
  31922. >    Class members must be defined with public, private, or protected.
  31923.    </P
  31924. ><P
  31925. >     <TABLE
  31926. WIDTH="100%"
  31927. BORDER="0"
  31928. CELLPADDING="0"
  31929. CELLSPACING="0"
  31930. CLASS="EXAMPLE"
  31931. ><TR
  31932. ><TD
  31933. ><DIV
  31934. CLASS="example"
  31935. ><A
  31936. NAME="AEN5470"
  31937. ></A
  31938. ><P
  31939. ><B
  31940. >Example 19-8. Member declaration</B
  31941. ></P
  31942. ><TABLE
  31943. BORDER="0"
  31944. BGCOLOR="#E0E0E0"
  31945. CELLPADDING="5"
  31946. ><TR
  31947. ><TD
  31948. ><PRE
  31949. CLASS="php"
  31950. ><?php
  31951. /**
  31952.  * Define MyClass
  31953.  */
  31954. class MyClass
  31955. {
  31956.     public $public = 'Public';
  31957.     protected $protected = 'Protected';
  31958.     private $private = 'Private';
  31959.  
  31960.     function printHello()
  31961.     {
  31962.         echo $this->public;
  31963.         echo $this->protected;
  31964.         echo $this->private;
  31965.     }
  31966. }
  31967.  
  31968. $obj = new MyClass();
  31969. echo $obj->public; // Works
  31970. echo $obj->protected; // Fatal Error
  31971. echo $obj->private; // Fatal Error
  31972. $obj->printHello(); // Shows Public, Protected and Private
  31973.  
  31974.  
  31975. /**
  31976.  * Define MyClass2
  31977.  */
  31978. class MyClass2 extends MyClass
  31979. {
  31980.     // We can redeclare the public and protected method, but not private
  31981.     protected $protected = 'Protected2';
  31982.  
  31983.     function printHello()
  31984.     {
  31985.         echo $this->public;
  31986.         echo $this->protected;
  31987.         echo $this->private;
  31988.     }
  31989. }
  31990.  
  31991. $obj2 = new MyClass2();
  31992. echo $obj->public; // Works
  31993. echo $obj2->private; // Undefined
  31994. echo $obj2->protected; // Fatal Error
  31995. $obj2->printHello(); // Shows Public, Protected2, not Private
  31996.  
  31997. ?></PRE
  31998. ></TD
  31999. ></TR
  32000. ></TABLE
  32001. ></DIV
  32002. ></TD
  32003. ></TR
  32004. ></TABLE
  32005. >
  32006.    </P
  32007. ><DIV
  32008. CLASS="note"
  32009. ><BLOCKQUOTE
  32010. CLASS="note"
  32011. ><P
  32012. ><B
  32013. >Note: </B
  32014. >
  32015.      The PHP 4 method of declaring a variable with the
  32016.      <SPAN
  32017. CLASS="emphasis"
  32018. ><I
  32019. CLASS="emphasis"
  32020. >var</I
  32021. ></SPAN
  32022. > keyword is no longer valid
  32023.      for PHP 5 objects. For compatibility a variable declared
  32024.      in php will be assumed with public visibility, and a
  32025.      <TT
  32026. CLASS="constant"
  32027. ><B
  32028. >E_STRICT</B
  32029. ></TT
  32030. > warning will be issued.
  32031.     </P
  32032. ></BLOCKQUOTE
  32033. ></DIV
  32034. ></DIV
  32035. ><DIV
  32036. CLASS="sect2"
  32037. ><HR><H3
  32038. CLASS="sect2"
  32039. ><A
  32040. NAME="language.oop5.visiblity-methods"
  32041. >Method Visibility</A
  32042. ></H3
  32043. ><P
  32044. >     Class methods must be defined with public, private, or protected. Methods
  32045.     without any declaration are defined as public.
  32046.    </P
  32047. ><P
  32048. >     <TABLE
  32049. WIDTH="100%"
  32050. BORDER="0"
  32051. CELLPADDING="0"
  32052. CELLSPACING="0"
  32053. CLASS="EXAMPLE"
  32054. ><TR
  32055. ><TD
  32056. ><DIV
  32057. CLASS="example"
  32058. ><A
  32059. NAME="AEN5481"
  32060. ></A
  32061. ><P
  32062. ><B
  32063. >Example 19-9. Method Declaration</B
  32064. ></P
  32065. ><TABLE
  32066. BORDER="0"
  32067. BGCOLOR="#E0E0E0"
  32068. CELLPADDING="5"
  32069. ><TR
  32070. ><TD
  32071. ><PRE
  32072. CLASS="php"
  32073. ><?php
  32074. /**
  32075.  * Define MyClass
  32076.  */
  32077. class MyClass
  32078. {
  32079.     // Contructors must be public
  32080.     public function __construct() { }
  32081.  
  32082.     // Declare a public method
  32083.     public function MyPublic() { }
  32084.  
  32085.     // Declare a protected method
  32086.     protected function MyProtected() { }
  32087.  
  32088.     // Declare a private method
  32089.     private function MyPrivate() { }
  32090.  
  32091.     // This is public
  32092.     function Foo()
  32093.     {
  32094.         $this->MyPublic();
  32095.         $this->MyProtected();
  32096.         $this->MyPrivate();
  32097.     }
  32098. }
  32099.  
  32100. $myclass = new MyClass;
  32101. $myclass->MyPublic(); // Works
  32102. $myclass->MyProtected(); // Fatal Error
  32103. $myclass->MyPrivate(); // Fatal Error
  32104. $myclass->Foo(); // Public, Protected and Private work
  32105.  
  32106.  
  32107. /**
  32108.  * Define MyClass2
  32109.  */
  32110. class MyClass2 extends MyClass
  32111. {
  32112.     // This is public
  32113.     function Foo2()
  32114.     {
  32115.         $this->MyPublic();
  32116.         $this->MyProtected();
  32117.         $this->MyPrivate(); // Fatal Error
  32118.     }
  32119. }
  32120.  
  32121. $myclass2 = new MyClass2;
  32122. $myclass2->MyPublic(); // Works
  32123. $myclass2->Foo2(); // Public and Protected work, not Private
  32124. ?></PRE
  32125. ></TD
  32126. ></TR
  32127. ></TABLE
  32128. ></DIV
  32129. ></TD
  32130. ></TR
  32131. ></TABLE
  32132. >
  32133.    </P
  32134. ></DIV
  32135. ></DIV
  32136. ><DIV
  32137. CLASS="sect1"
  32138. ><HR><H2
  32139. CLASS="sect1"
  32140. ><A
  32141. NAME="language.oop5.paamayim-nekudotayim"
  32142. >Scope Resolution Operator (::)</A
  32143. ></H2
  32144. ><P
  32145. >    The Scope Resolution Operator (also called Paamayim Nekudotayim) or in
  32146.    simpler terms, the double colon, is a token that allows access to 
  32147.    <A
  32148. HREF="#language.oop5.static"
  32149. >static</A
  32150. >,
  32151.    <A
  32152. HREF="#language.oop5.constants"
  32153. >constant</A
  32154. >, and overridden 
  32155.    members or methods of a class. 
  32156.   </P
  32157. ><P
  32158. >    When referencing these items from outside the class definition, use
  32159.    the name of the class.
  32160.   </P
  32161. ><P
  32162. >    Paamayim Nekudotayim would, at first, seem like a strange choice for
  32163.    naming a double-colon. However, while writing the Zend Engine 0.5
  32164.    (which powers PHP 3), that's what the Zend team decided to call it.
  32165.    It actually does mean double-colon - in Hebrew!
  32166.   </P
  32167. ><TABLE
  32168. WIDTH="100%"
  32169. BORDER="0"
  32170. CELLPADDING="0"
  32171. CELLSPACING="0"
  32172. CLASS="EXAMPLE"
  32173. ><TR
  32174. ><TD
  32175. ><DIV
  32176. CLASS="example"
  32177. ><A
  32178. NAME="AEN5491"
  32179. ></A
  32180. ><P
  32181. ><B
  32182. >Example 19-10. :: from outside the class definition</B
  32183. ></P
  32184. ><TABLE
  32185. BORDER="0"
  32186. BGCOLOR="#E0E0E0"
  32187. CELLPADDING="5"
  32188. ><TR
  32189. ><TD
  32190. ><PRE
  32191. CLASS="php"
  32192. ><?php
  32193. class MyClass {
  32194.     const CONST_VALUE = 'A constant value';
  32195. }
  32196.  
  32197. echo MyClass::CONST_VALUE;
  32198. ?></PRE
  32199. ></TD
  32200. ></TR
  32201. ></TABLE
  32202. ></DIV
  32203. ></TD
  32204. ></TR
  32205. ></TABLE
  32206. ><P
  32207. >    Two special keywords <VAR
  32208. CLASS="varname"
  32209. >self</VAR
  32210. > and <VAR
  32211. CLASS="varname"
  32212. >parent</VAR
  32213. >
  32214.    are used to access members or methods from inside the class definition.
  32215.   </P
  32216. ><TABLE
  32217. WIDTH="100%"
  32218. BORDER="0"
  32219. CELLPADDING="0"
  32220. CELLSPACING="0"
  32221. CLASS="EXAMPLE"
  32222. ><TR
  32223. ><TD
  32224. ><DIV
  32225. CLASS="example"
  32226. ><A
  32227. NAME="AEN5497"
  32228. ></A
  32229. ><P
  32230. ><B
  32231. >Example 19-11. :: from inside the class definition</B
  32232. ></P
  32233. ><TABLE
  32234. BORDER="0"
  32235. BGCOLOR="#E0E0E0"
  32236. CELLPADDING="5"
  32237. ><TR
  32238. ><TD
  32239. ><PRE
  32240. CLASS="php"
  32241. ><?php
  32242. class OtherClass extends MyClass
  32243. {
  32244.     public static $my_static = 'static var';
  32245.  
  32246.     public static function doubleColon() {
  32247.         echo parent::CONST_VALUE . "\n";
  32248.         echo self::$my_static . "\n";
  32249.     }
  32250. }
  32251.  
  32252. OtherClass::doubleColon();
  32253. ?></PRE
  32254. ></TD
  32255. ></TR
  32256. ></TABLE
  32257. ></DIV
  32258. ></TD
  32259. ></TR
  32260. ></TABLE
  32261. ><P
  32262. >    When an extending class overrides the parents definition of a method,
  32263.    PHP will not call the parent's method. It's up to the extended class
  32264.    on whether or not the parent's method is called. This also applies to <A
  32265. HREF="#language.oop5.decon"
  32266. >Constructors and Destructors</A
  32267. >, <A
  32268. HREF="#language.oop5.overloading"
  32269. >Overloading</A
  32270. >, and <A
  32271. HREF="#language.oop5.magic"
  32272. >Magic</A
  32273. > method definitions.
  32274.   </P
  32275. ><TABLE
  32276. WIDTH="100%"
  32277. BORDER="0"
  32278. CELLPADDING="0"
  32279. CELLSPACING="0"
  32280. CLASS="EXAMPLE"
  32281. ><TR
  32282. ><TD
  32283. ><DIV
  32284. CLASS="example"
  32285. ><A
  32286. NAME="AEN5504"
  32287. ></A
  32288. ><P
  32289. ><B
  32290. >Example 19-12. Calling a parent's method</B
  32291. ></P
  32292. ><TABLE
  32293. BORDER="0"
  32294. BGCOLOR="#E0E0E0"
  32295. CELLPADDING="5"
  32296. ><TR
  32297. ><TD
  32298. ><PRE
  32299. CLASS="php"
  32300. ><?php
  32301. class MyClass
  32302. {
  32303.     protected function myFunc() {
  32304.         echo "MyClass::myFunc()\n";
  32305.     }
  32306. }
  32307.  
  32308. class OtherClass extends MyClass
  32309. {
  32310.     // Override parent's definition
  32311.     public function myFunc()
  32312.     {
  32313.         // But still call the parent function
  32314.         parent::myFunc();
  32315.         echo "OtherClass::myFunc()\n";
  32316.     }
  32317. }
  32318.  
  32319. $class = new OtherClass();
  32320. $class->myFunc();
  32321. ?></PRE
  32322. ></TD
  32323. ></TR
  32324. ></TABLE
  32325. ></DIV
  32326. ></TD
  32327. ></TR
  32328. ></TABLE
  32329. ></DIV
  32330. ><DIV
  32331. CLASS="sect1"
  32332. ><HR><H2
  32333. CLASS="sect1"
  32334. ><A
  32335. NAME="language.oop5.static"
  32336. >Static Keyword</A
  32337. ></H2
  32338. ><P
  32339. >    Declaring class members or methods as static, makes them callable
  32340.    from outside the object context. A member or method declared
  32341.    with static can not be accessed with a variable that is an instance
  32342.    of the object and cannot be re-defined in an extending class.
  32343.   </P
  32344. ><P
  32345. >    The static declaration must be after the visibility declaration. For 
  32346.    compatibility with PHP 4, if no <A
  32347. HREF="#language.oop5.visibility"
  32348. >visibility</A
  32349. >
  32350.    declaration is used, then the member or method will be treated
  32351.    as if it was declared as <VAR
  32352. CLASS="literal"
  32353. >public static</VAR
  32354. >.
  32355.   </P
  32356. ><P
  32357. >    Because static methods are callable without an instance of
  32358.    the object created, the pseudo variable <VAR
  32359. CLASS="varname"
  32360. >$this</VAR
  32361. > is
  32362.    not available inside the method declared as static.
  32363.   </P
  32364. ><P
  32365. >    In fact <VAR
  32366. CLASS="literal"
  32367. >static</VAR
  32368. > method calls are resolved at compile 
  32369.    time. When using an explicit class name the method is already identified
  32370.    completley and no inheritance rules apply. If the call is done by 
  32371.    <VAR
  32372. CLASS="literal"
  32373. >self</VAR
  32374. > then <VAR
  32375. CLASS="literal"
  32376. >self</VAR
  32377. > is translated to 
  32378.    the current class, that is the class the code belongs to. Here also no 
  32379.    inheritance rules apply.
  32380.   </P
  32381. ><P
  32382. >    Static properties cannot be accessed through the object using the arrow
  32383.    operator ->.
  32384.   </P
  32385. ><TABLE
  32386. WIDTH="100%"
  32387. BORDER="0"
  32388. CELLPADDING="0"
  32389. CELLSPACING="0"
  32390. CLASS="EXAMPLE"
  32391. ><TR
  32392. ><TD
  32393. ><DIV
  32394. CLASS="example"
  32395. ><A
  32396. NAME="AEN5520"
  32397. ></A
  32398. ><P
  32399. ><B
  32400. >Example 19-13. Static member example</B
  32401. ></P
  32402. ><TABLE
  32403. BORDER="0"
  32404. BGCOLOR="#E0E0E0"
  32405. CELLPADDING="5"
  32406. ><TR
  32407. ><TD
  32408. ><PRE
  32409. CLASS="php"
  32410. ><?php
  32411. class Foo
  32412. {
  32413.     public static $my_static = 'foo';
  32414.  
  32415.     public function staticValue() {
  32416.         return self::$my_static;
  32417.     }
  32418. }
  32419.  
  32420. class Bar extends Foo
  32421. {
  32422.     public function fooStatic() {
  32423.         return parent::$my_static;
  32424.     }
  32425. }
  32426.  
  32427.  
  32428. print Foo::$my_static . "\n";
  32429.  
  32430. $foo = new Foo();
  32431. print $foo->staticValue() . "\n";
  32432. print $foo->my_static . "\n";      // Undefined "Property" my_static 
  32433.  
  32434. // $foo::my_static is not possible
  32435.  
  32436. print Bar::$my_static . "\n";
  32437. $bar = new Bar();
  32438. print $bar->fooStatic() . "\n";
  32439. ?></PRE
  32440. ></TD
  32441. ></TR
  32442. ></TABLE
  32443. ></DIV
  32444. ></TD
  32445. ></TR
  32446. ></TABLE
  32447. ><TABLE
  32448. WIDTH="100%"
  32449. BORDER="0"
  32450. CELLPADDING="0"
  32451. CELLSPACING="0"
  32452. CLASS="EXAMPLE"
  32453. ><TR
  32454. ><TD
  32455. ><DIV
  32456. CLASS="example"
  32457. ><A
  32458. NAME="AEN5523"
  32459. ></A
  32460. ><P
  32461. ><B
  32462. >Example 19-14. Static method example</B
  32463. ></P
  32464. ><TABLE
  32465. BORDER="0"
  32466. BGCOLOR="#E0E0E0"
  32467. CELLPADDING="5"
  32468. ><TR
  32469. ><TD
  32470. ><PRE
  32471. CLASS="php"
  32472. ><?php
  32473. class Foo {
  32474.     public static function aStaticMethod() {
  32475.         // ...
  32476.     }
  32477. }
  32478.  
  32479. Foo::aStaticMethod();
  32480. ?></PRE
  32481. ></TD
  32482. ></TR
  32483. ></TABLE
  32484. ></DIV
  32485. ></TD
  32486. ></TR
  32487. ></TABLE
  32488. ></DIV
  32489. ><DIV
  32490. CLASS="sect1"
  32491. ><HR><H2
  32492. CLASS="sect1"
  32493. ><A
  32494. NAME="language.oop5.constants"
  32495. >Object Constants</A
  32496. ></H2
  32497. ><P
  32498. >    It is possible to define constant values on a per-class basis remaining the
  32499.    same and unchangeable. Constants differ from normal variables in that you
  32500.    don't use the <VAR
  32501. CLASS="varname"
  32502. >$</VAR
  32503. > symbol to declare or use them.  Like
  32504.    <A
  32505. HREF="#language.oop5.static"
  32506. >static</A
  32507. > members, constant values
  32508.    can not be accessed from an instance of the object.
  32509.   </P
  32510. ><TABLE
  32511. WIDTH="100%"
  32512. BORDER="0"
  32513. CELLPADDING="0"
  32514. CELLSPACING="0"
  32515. CLASS="EXAMPLE"
  32516. ><TR
  32517. ><TD
  32518. ><DIV
  32519. CLASS="example"
  32520. ><A
  32521. NAME="AEN5531"
  32522. ></A
  32523. ><P
  32524. ><B
  32525. >Example 19-15. Defining and using a constant</B
  32526. ></P
  32527. ><TABLE
  32528. BORDER="0"
  32529. BGCOLOR="#E0E0E0"
  32530. CELLPADDING="5"
  32531. ><TR
  32532. ><TD
  32533. ><PRE
  32534. CLASS="php"
  32535. ><?php
  32536. class MyClass
  32537. {
  32538.     const constant = 'constant value';
  32539.  
  32540.     function showConstant() {
  32541.         echo  self::constant . "\n";
  32542.     }
  32543. }
  32544.  
  32545. echo MyClass::constant . "\n";
  32546.  
  32547. $class = new MyClass();
  32548. $class->showConstant();
  32549. // echo $class::constant;  is not allowed
  32550. ?></PRE
  32551. ></TD
  32552. ></TR
  32553. ></TABLE
  32554. ></DIV
  32555. ></TD
  32556. ></TR
  32557. ></TABLE
  32558. ></DIV
  32559. ><DIV
  32560. CLASS="sect1"
  32561. ><HR><H2
  32562. CLASS="sect1"
  32563. ><A
  32564. NAME="language.oop5.abstract"
  32565. >Object Abstraction</A
  32566. ></H2
  32567. ><P
  32568. >    PHP 5 introduces abstract classes and methods. It is not allowed to create
  32569.    an instance of a class that has been defined as abstract.  Any class that
  32570.    contains at least one abstract method must also be abstract.  Methods
  32571.    defined as abstract simply declare the method's signature they cannot
  32572.    define the implementation.
  32573.   </P
  32574. ><P
  32575. >    The class that implements the abstract method must define with the same
  32576.    <A
  32577. HREF="#language.oop5.visibility"
  32578. >visibillity</A
  32579. > or weaker. If the
  32580.    abstract method is defined as protected, the function implementation must be
  32581.    defined as either protected or public.
  32582.   </P
  32583. ><TABLE
  32584. WIDTH="100%"
  32585. BORDER="0"
  32586. CELLPADDING="0"
  32587. CELLSPACING="0"
  32588. CLASS="EXAMPLE"
  32589. ><TR
  32590. ><TD
  32591. ><DIV
  32592. CLASS="example"
  32593. ><A
  32594. NAME="AEN5539"
  32595. ></A
  32596. ><P
  32597. ><B
  32598. >Example 19-16. Abstract class example</B
  32599. ></P
  32600. ><TABLE
  32601. BORDER="0"
  32602. BGCOLOR="#E0E0E0"
  32603. CELLPADDING="5"
  32604. ><TR
  32605. ><TD
  32606. ><PRE
  32607. CLASS="php"
  32608. ><?php
  32609. abstract class AbstractClass
  32610. {
  32611.     // Force Extending class to define this method
  32612.     abstract protected function getValue();
  32613.  
  32614.     // Common method
  32615.     public function printOut() {
  32616.         print $this->getValue();
  32617.     }
  32618. }
  32619.  
  32620. class ConcreteClass1 extends AbstractClass
  32621. {
  32622.     protected function getValue() {
  32623.         return "ConcreteClass1";
  32624.     }
  32625. }
  32626.  
  32627. class ConcreteClass2 extends AbstractClass
  32628. {
  32629.     protected function getValue() {
  32630.         return "ConcreteClass2";
  32631.     }
  32632.  
  32633. }
  32634.  
  32635. $class1 = new ConcreteClass1;
  32636. $class1->printOut();
  32637.  
  32638. $class2 = new ConcreteClass2;
  32639. $class2->printOut();
  32640. ?></PRE
  32641. ></TD
  32642. ></TR
  32643. ></TABLE
  32644. ></DIV
  32645. ></TD
  32646. ></TR
  32647. ></TABLE
  32648. ><P
  32649. >     Old code that has no user-defined classes or functions named
  32650.     'abstract' should run without modifications.
  32651.    </P
  32652. ></DIV
  32653. ><DIV
  32654. CLASS="sect1"
  32655. ><HR><H2
  32656. CLASS="sect1"
  32657. ><A
  32658. NAME="language.oop5.interfaces"
  32659. >Object Interfaces</A
  32660. ></H2
  32661. ><P
  32662. >    Object interfaces allow you to create code which specifies which methods a
  32663.    class must implement, without having to define how these methods are
  32664.    handled.
  32665.   </P
  32666. ><P
  32667. >    Interfaces are defined using the interface keyword, in the same way as a
  32668.    standard class, but without any of the methods having their contents
  32669.    defined. Classes which implement an interface should do so using the
  32670.    implements keyword, and must have definitions for all the methods listed
  32671.    in the interface. Classes may implement more than one interface if desired
  32672.    by listing each interface split by a comma.
  32673.   </P
  32674. ><P
  32675. >    All methods declared in an interface must be public, this is the nature of an
  32676.    interface.
  32677.   </P
  32678. ><P
  32679. >    Stating that a class implements an interface, and then not implementing all
  32680.    the methods in the interface will result in a fatal error telling you which
  32681.    methods have not been implemented.
  32682.   </P
  32683. ><TABLE
  32684. WIDTH="100%"
  32685. BORDER="0"
  32686. CELLPADDING="0"
  32687. CELLSPACING="0"
  32688. CLASS="EXAMPLE"
  32689. ><TR
  32690. ><TD
  32691. ><DIV
  32692. CLASS="example"
  32693. ><A
  32694. NAME="AEN5549"
  32695. ></A
  32696. ><P
  32697. ><B
  32698. >Example 19-17. Interface example</B
  32699. ></P
  32700. ><TABLE
  32701. BORDER="0"
  32702. BGCOLOR="#E0E0E0"
  32703. CELLPADDING="5"
  32704. ><TR
  32705. ><TD
  32706. ><PRE
  32707. CLASS="php"
  32708. ><?php
  32709. // Declare the interface 'iTemplate'
  32710. interface iTemplate
  32711. {
  32712.     public function setVariable($name, $var);
  32713.     public function getHtml($template);
  32714. }
  32715.  
  32716. // Implement the interface
  32717. // This will work
  32718. class Template implements iTemplate
  32719. {
  32720.     private $vars = array();
  32721.   
  32722.     public function setVariable($name, $var)
  32723.     {
  32724.         $this->vars[$name] = $var;
  32725.     }
  32726.   
  32727.     public function getHtml($template)
  32728.     {
  32729.         foreach($this->vars as $name => $value) {
  32730.             $template = str_replace('{' . $name . '}', $value, $template);
  32731.         }
  32732.  
  32733.         return $template;
  32734.     }
  32735. }
  32736.  
  32737. // This will not work
  32738. // Fatal error: Class BadTemplate contains 1 abstract methods
  32739. // and must therefore be declared abstract (iTemplate::getHtml)
  32740. class BadTemplate implements iTemplate
  32741. {
  32742.     private $vars = array();
  32743.   
  32744.     public function setVariable($name, $var)
  32745.     {
  32746.         $this->vars[$name] = $var;
  32747.     }
  32748. }
  32749.  
  32750. ?></PRE
  32751. ></TD
  32752. ></TR
  32753. ></TABLE
  32754. ></DIV
  32755. ></TD
  32756. ></TR
  32757. ></TABLE
  32758. ></DIV
  32759. ><DIV
  32760. CLASS="sect1"
  32761. ><HR><H2
  32762. CLASS="sect1"
  32763. ><A
  32764. NAME="language.oop5.overloading"
  32765. >Overloading</A
  32766. ></H2
  32767. ><P
  32768. >    Both method calls and member accesses can be overloaded via the
  32769.    __call, __get and __set methods. These methods will only be
  32770.    triggered when your object or inherited object doesn't contain the 
  32771.    member or method you're trying to access.
  32772.   </P
  32773. ><DIV
  32774. CLASS="sect2"
  32775. ><HR><H3
  32776. CLASS="sect2"
  32777. ><A
  32778. NAME="language.oop5.overloading.members"
  32779. >Member overloading</A
  32780. ></H3
  32781. >void <B
  32782. CLASS="methodname"
  32783. >__set</B
  32784. > ( string name, mixed value)<BR
  32785. ></BR
  32786. >mixed <B
  32787. CLASS="methodname"
  32788. >__get</B
  32789. > ( mixed name)<BR
  32790. ></BR
  32791. ><P
  32792. >     Class members can be overloaded to run custom code defined in your class
  32793.     by defining these specially named methods. The <VAR
  32794. CLASS="varname"
  32795. >$name</VAR
  32796. > 
  32797.     parameter used is the name of the variable that should be set or retrieved.
  32798.     The __set() method's <VAR
  32799. CLASS="varname"
  32800. >$value</VAR
  32801. > parameter specifies the 
  32802.     value that the object should set set the <VAR
  32803. CLASS="varname"
  32804. >$name</VAR
  32805. >.
  32806.    </P
  32807. ><TABLE
  32808. WIDTH="100%"
  32809. BORDER="0"
  32810. CELLPADDING="0"
  32811. CELLSPACING="0"
  32812. CLASS="EXAMPLE"
  32813. ><TR
  32814. ><TD
  32815. ><DIV
  32816. CLASS="example"
  32817. ><A
  32818. NAME="AEN5576"
  32819. ></A
  32820. ><P
  32821. ><B
  32822. >Example 19-18. overloading with __get and __set example</B
  32823. ></P
  32824. ><TABLE
  32825. BORDER="0"
  32826. BGCOLOR="#E0E0E0"
  32827. CELLPADDING="5"
  32828. ><TR
  32829. ><TD
  32830. ><PRE
  32831. CLASS="php"
  32832. ><?php
  32833. class Setter
  32834. {
  32835.     public $n;
  32836.     private $x = array("a" => 1, "b" => 2, "c" => 3);
  32837.  
  32838.     function __get($nm)
  32839.     {
  32840.         print "Getting [$nm]\n";
  32841.  
  32842.         if (isset($this->x[$nm])) {
  32843.             $r = $this->x[$nm];
  32844.             print "Returning: $r\n";
  32845.             return $r;
  32846.         } else {
  32847.             echo "Nothing!\n";
  32848.         }
  32849.     }
  32850.  
  32851.     function __set($nm, $val)
  32852.     {
  32853.         print "Setting [$nm] to $val\n";
  32854.  
  32855.         if (isset($this->x[$nm])) {
  32856.             $this->x[$nm] = $val;
  32857.             echo "OK!\n";
  32858.         } else {
  32859.             echo "Not OK!\n";
  32860.         }
  32861.     }
  32862. }
  32863.  
  32864. $foo = new Setter();
  32865. $foo->n = 1;
  32866. $foo->a = 100;
  32867. $foo->a++;
  32868. $foo->z++;
  32869. var_dump($foo);
  32870. ?></PRE
  32871. ></TD
  32872. ></TR
  32873. ></TABLE
  32874. ><P
  32875. >      Will output:
  32876.     </P
  32877. ><TABLE
  32878. BORDER="0"
  32879. BGCOLOR="#E0E0E0"
  32880. CELLPADDING="5"
  32881. ><TR
  32882. ><TD
  32883. ><PRE
  32884. CLASS="php"
  32885. >Setting [a] to 100
  32886. OK!
  32887. Getting [a]
  32888. Returning: 100
  32889. Setting [a] to 101
  32890. OK!
  32891. Getting [z]
  32892. Nothing!
  32893. Setting [z] to 1
  32894. Not OK!
  32895. object(Setter)#1 (2) {
  32896.     ["n"]=>
  32897.     int(1)
  32898.     ["x:private"]=>
  32899.     array(3) {
  32900.         ["a"]=>
  32901.         int(101)
  32902.         ["b"]=>
  32903.         int(2)
  32904.         ["c"]=>
  32905.         int(3)
  32906.     }
  32907. }</PRE
  32908. ></TD
  32909. ></TR
  32910. ></TABLE
  32911. ></DIV
  32912. ></TD
  32913. ></TR
  32914. ></TABLE
  32915. ></DIV
  32916. ><DIV
  32917. CLASS="sect2"
  32918. ><HR><H3
  32919. CLASS="sect2"
  32920. ><A
  32921. NAME="language.oop5.overloading.methods"
  32922. >Method overloading</A
  32923. ></H3
  32924. >mixed <B
  32925. CLASS="methodname"
  32926. >__call</B
  32927. > ( string name, array arguments)<BR
  32928. ></BR
  32929. ><P
  32930. >     Class methods can be overloaded to run custom code defined in your class
  32931.     by defining this specially named method. The <VAR
  32932. CLASS="varname"
  32933. >$name</VAR
  32934. > 
  32935.     parameter used is the name as the function name that was requested 
  32936.     to be used. The arguments that were passed in the function will be 
  32937.     defined as an array in the <VAR
  32938. CLASS="varname"
  32939. >$arguments</VAR
  32940. > parameter.
  32941.     The value returned from the __call() method will be returned to the
  32942.     caller of the method.
  32943.    </P
  32944. ><TABLE
  32945. WIDTH="100%"
  32946. BORDER="0"
  32947. CELLPADDING="0"
  32948. CELLSPACING="0"
  32949. CLASS="EXAMPLE"
  32950. ><TR
  32951. ><TD
  32952. ><DIV
  32953. CLASS="example"
  32954. ><A
  32955. NAME="AEN5595"
  32956. ></A
  32957. ><P
  32958. ><B
  32959. >Example 19-19. overloading with __call example</B
  32960. ></P
  32961. ><TABLE
  32962. BORDER="0"
  32963. BGCOLOR="#E0E0E0"
  32964. CELLPADDING="5"
  32965. ><TR
  32966. ><TD
  32967. ><PRE
  32968. CLASS="php"
  32969. ><?php
  32970. class Caller
  32971. {
  32972.     private $x = array(1, 2, 3);
  32973.  
  32974.     function __call($m, $a)
  32975.     {
  32976.         print "Method $m called:\n";
  32977.         var_dump($a);
  32978.         return $this->x;
  32979.     }
  32980. }
  32981.  
  32982. $foo = new Caller();
  32983. $a = $foo->test(1, "2", 3.4, true);
  32984. var_dump($a);
  32985. ?></PRE
  32986. ></TD
  32987. ></TR
  32988. ></TABLE
  32989. ><P
  32990. >      Will Output:
  32991.     </P
  32992. ><TABLE
  32993. BORDER="0"
  32994. BGCOLOR="#E0E0E0"
  32995. CELLPADDING="5"
  32996. ><TR
  32997. ><TD
  32998. ><PRE
  32999. CLASS="php"
  33000. >Method test called:
  33001. array(4) {
  33002.     [0]=>
  33003.     int(1)
  33004.     [1]=>
  33005.     string(1) "2"
  33006.     [2]=>
  33007.     float(3.4)
  33008.     [3]=>
  33009.     bool(true)
  33010. }
  33011. array(3) {
  33012.     [0]=>
  33013.     int(1)
  33014.     [1]=>
  33015.     int(2)
  33016.     [2]=>
  33017.     int(3)
  33018. }</PRE
  33019. ></TD
  33020. ></TR
  33021. ></TABLE
  33022. ></DIV
  33023. ></TD
  33024. ></TR
  33025. ></TABLE
  33026. ></DIV
  33027. ></DIV
  33028. ><DIV
  33029. CLASS="sect1"
  33030. ><HR><H2
  33031. CLASS="sect1"
  33032. ><A
  33033. NAME="language.oop5.iterations"
  33034. >Object Iteration</A
  33035. ></H2
  33036. ><P
  33037. >
  33038.    PHP 5 provides a way for objects to be defined so it is possible to iterate
  33039.    through a list of items, with, for example a <A
  33040. HREF="#control-structures.foreach"
  33041. >foreach</A
  33042. > statement. By default,
  33043.    all <A
  33044. HREF="#language.oop5.visibility"
  33045. >visible</A
  33046. > properties will be used
  33047.    for the iteration.
  33048.  
  33049.   </P
  33050. ><TABLE
  33051. WIDTH="100%"
  33052. BORDER="0"
  33053. CELLPADDING="0"
  33054. CELLSPACING="0"
  33055. CLASS="EXAMPLE"
  33056. ><TR
  33057. ><TD
  33058. ><DIV
  33059. CLASS="example"
  33060. ><A
  33061. NAME="AEN5605"
  33062. ></A
  33063. ><P
  33064. ><B
  33065. >Example 19-20. Simple Object Iteration</B
  33066. ></P
  33067. ><TABLE
  33068. BORDER="0"
  33069. BGCOLOR="#E0E0E0"
  33070. CELLPADDING="5"
  33071. ><TR
  33072. ><TD
  33073. ><PRE
  33074. CLASS="php"
  33075. ><?php
  33076. class MyClass
  33077. {
  33078.     public $var1 = 'value 1';
  33079.     public $var2 = 'value 2';
  33080.     public $var3 = 'value 3';
  33081.  
  33082.     protected $protected = 'protected var';
  33083.     private   $private   = 'private var';
  33084.  
  33085.     function iterateVisible() {
  33086.        echo "MyClass::iterateVisible:\n";
  33087.        foreach($this as $key => $value) {
  33088.            print "$key => $value\n";
  33089.        }
  33090.     }
  33091. }
  33092.  
  33093. $class = new MyClass();
  33094.  
  33095. foreach($class as $key => $value) {
  33096.     print "$key => $value\n";
  33097. }
  33098. echo "\n";
  33099.  
  33100.  
  33101. $class->iterateVisible();
  33102.  
  33103. ?></PRE
  33104. ></TD
  33105. ></TR
  33106. ></TABLE
  33107. ><P
  33108. >The above example will output:</P
  33109. ><TABLE
  33110. BORDER="0"
  33111. BGCOLOR="#E0E0E0"
  33112. CELLPADDING="5"
  33113. ><TR
  33114. ><TD
  33115. ><PRE
  33116. CLASS="php"
  33117. >var1 => value 1
  33118. var2 => value 2
  33119. var3 => value 3
  33120.  
  33121. MyClass::iterateVisible:
  33122. var1 => value 1
  33123. var2 => value 2
  33124. var3 => value 3
  33125. protected => protected var
  33126. private => private var</PRE
  33127. ></TD
  33128. ></TR
  33129. ></TABLE
  33130. ></DIV
  33131. ></TD
  33132. ></TR
  33133. ></TABLE
  33134. ><P
  33135. >   As the output shows, the <A
  33136. HREF="#control-structures.foreach"
  33137. >foreach</A
  33138. > iterated through all
  33139.   <A
  33140. HREF="#language.oop5.visibility"
  33141. >visible</A
  33142. > variables that can be
  33143.   accessed. To take it a step further you can <VAR
  33144. CLASS="varname"
  33145. >implement</VAR
  33146. > one
  33147.   of PHP 5's internal <A
  33148. HREF="#language.oop5.interfaces"
  33149. >interface</A
  33150. > named
  33151.   <VAR
  33152. CLASS="varname"
  33153. >Iterator</VAR
  33154. >. This allows the object to decide what and how
  33155.   the object will be iterated.
  33156.  </P
  33157. ><TABLE
  33158. WIDTH="100%"
  33159. BORDER="0"
  33160. CELLPADDING="0"
  33161. CELLSPACING="0"
  33162. CLASS="EXAMPLE"
  33163. ><TR
  33164. ><TD
  33165. ><DIV
  33166. CLASS="example"
  33167. ><A
  33168. NAME="AEN5616"
  33169. ></A
  33170. ><P
  33171. ><B
  33172. >Example 19-21. Object Iteration implementing Iterator</B
  33173. ></P
  33174. ><TABLE
  33175. BORDER="0"
  33176. BGCOLOR="#E0E0E0"
  33177. CELLPADDING="5"
  33178. ><TR
  33179. ><TD
  33180. ><PRE
  33181. CLASS="php"
  33182. ><?php
  33183. class MyIterator implements Iterator
  33184. {
  33185.     private $var = array();
  33186.  
  33187.     public function __construct($array)
  33188.     {
  33189.         if (is_array($array)) {
  33190.             $this->var = $array;
  33191.         }
  33192.     }
  33193.  
  33194.     public function rewind() {
  33195.         echo "rewinding\n";
  33196.         reset($this->var);
  33197.     }
  33198.  
  33199.     public function current() {
  33200.         $var = current($this->var);
  33201.         echo "current: $var\n";
  33202.         return $var;
  33203.     }
  33204.  
  33205.     public function key() {
  33206.         $var = key($this->var);
  33207.         echo "key: $var\n";
  33208.         return $var;
  33209.     }
  33210.  
  33211.     public function next() {
  33212.         $var = next($this->var);
  33213.         echo "next: $var\n";
  33214.         return $var;
  33215.     }
  33216.  
  33217.     public function valid() {
  33218.         $var = $this->current() !== false;
  33219.         echo "valid: {$var}\n";
  33220.         return $var;
  33221.     }
  33222. }
  33223.  
  33224. $values = array(1,2,3);
  33225. $it = new MyIterator($values);
  33226.  
  33227. foreach ($it as $a => $b) {
  33228.     print "$a: $b\n";
  33229. }
  33230. ?></PRE
  33231. ></TD
  33232. ></TR
  33233. ></TABLE
  33234. ><P
  33235. >      Will output:
  33236.    </P
  33237. ><TABLE
  33238. BORDER="0"
  33239. BGCOLOR="#E0E0E0"
  33240. CELLPADDING="5"
  33241. ><TR
  33242. ><TD
  33243. ><PRE
  33244. CLASS="php"
  33245. >rewinding
  33246. current: 1
  33247. valid: 1
  33248. current: 1
  33249. key: 0
  33250. 0: 1
  33251. next: 2
  33252. current: 2
  33253. valid: 1
  33254. current: 2
  33255. key: 1
  33256. 1: 2
  33257. next: 3
  33258. current: 3
  33259. valid: 1
  33260. current: 3
  33261. key: 2
  33262. 2: 3
  33263. next:
  33264. current:
  33265. valid:</PRE
  33266. ></TD
  33267. ></TR
  33268. ></TABLE
  33269. ></DIV
  33270. ></TD
  33271. ></TR
  33272. ></TABLE
  33273. ><P
  33274. >    You can also define your class so that it doesn't have to define
  33275.    all the <VAR
  33276. CLASS="varname"
  33277. >Iterator</VAR
  33278. > functions by simply implementing
  33279.    the PHP 5 <VAR
  33280. CLASS="varname"
  33281. >IteratorAggregate</VAR
  33282. > interface.
  33283.   </P
  33284. ><TABLE
  33285. WIDTH="100%"
  33286. BORDER="0"
  33287. CELLPADDING="0"
  33288. CELLSPACING="0"
  33289. CLASS="EXAMPLE"
  33290. ><TR
  33291. ><TD
  33292. ><DIV
  33293. CLASS="example"
  33294. ><A
  33295. NAME="AEN5624"
  33296. ></A
  33297. ><P
  33298. ><B
  33299. >Example 19-22. Object Iteration implementing IteratorAggregate</B
  33300. ></P
  33301. ><TABLE
  33302. BORDER="0"
  33303. BGCOLOR="#E0E0E0"
  33304. CELLPADDING="5"
  33305. ><TR
  33306. ><TD
  33307. ><PRE
  33308. CLASS="php"
  33309. ><?php
  33310. class MyCollection implements IteratorAggregate
  33311. {
  33312.     private $items = array();
  33313.     private $count = 0;
  33314.  
  33315.     // Required definition of interface IteratorAggregate
  33316.     public function getIterator() {
  33317.         return new MyIterator($this->items);
  33318.     }
  33319.  
  33320.     public function add($value) {
  33321.         $this->items[$this->count++] = $value;
  33322.     }
  33323. }
  33324.  
  33325. $coll = new MyCollection();
  33326. $coll->add('value 1');
  33327. $coll->add('value 2');
  33328. $coll->add('value 3');
  33329.  
  33330. foreach ($coll as $key => $val) {
  33331.     echo "key/value: [$key -> $val]\n\n";
  33332. }
  33333. ?></PRE
  33334. ></TD
  33335. ></TR
  33336. ></TABLE
  33337. ><P
  33338. >      Will output:
  33339.    </P
  33340. ><TABLE
  33341. BORDER="0"
  33342. BGCOLOR="#E0E0E0"
  33343. CELLPADDING="5"
  33344. ><TR
  33345. ><TD
  33346. ><PRE
  33347. CLASS="php"
  33348. >rewinding
  33349. current: value 1
  33350. valid: 1
  33351. current: value 1
  33352. key: 0
  33353. key/value: [0 -> value 1]
  33354.  
  33355. next: value 2
  33356. current: value 2
  33357. valid: 1
  33358. current: value 2
  33359. key: 1
  33360. key/value: [1 -> value 2]
  33361.  
  33362. next: value 3
  33363. current: value 3
  33364. valid: 1
  33365. current: value 3
  33366. key: 2
  33367. key/value: [2 -> value 3]
  33368.  
  33369. next:
  33370. current:
  33371. valid:</PRE
  33372. ></TD
  33373. ></TR
  33374. ></TABLE
  33375. ></DIV
  33376. ></TD
  33377. ></TR
  33378. ></TABLE
  33379. ><DIV
  33380. CLASS="note"
  33381. ><BLOCKQUOTE
  33382. CLASS="note"
  33383. ><P
  33384. ><B
  33385. >Note: </B
  33386. >
  33387.     For more examples of iterators, see the
  33388.     <A
  33389. HREF="#ref.spl"
  33390. >SPL Extension</A
  33391. >.
  33392.    </P
  33393. ></BLOCKQUOTE
  33394. ></DIV
  33395. ></DIV
  33396. ><DIV
  33397. CLASS="sect1"
  33398. ><HR><H2
  33399. CLASS="sect1"
  33400. ><A
  33401. NAME="language.oop5.patterns"
  33402. >Patterns</A
  33403. ></H2
  33404. ><P
  33405. >   Patterns are ways to describe best practices and good designs.
  33406.   They show a flexible solution to common programming problems.
  33407.  </P
  33408. ><DIV
  33409. CLASS="sect2"
  33410. ><HR><H3
  33411. CLASS="sect2"
  33412. ><A
  33413. NAME="language.oop5.patterns.factory"
  33414. >Factory</A
  33415. ></H3
  33416. ><P
  33417. >    The Factory pattern allows for the instantation of objects
  33418.    at runtime. It is called a Factory Pattern since it is
  33419.    responsible for "manufacturing" an object.
  33420.   </P
  33421. ><TABLE
  33422. WIDTH="100%"
  33423. BORDER="0"
  33424. CELLPADDING="0"
  33425. CELLSPACING="0"
  33426. CLASS="EXAMPLE"
  33427. ><TR
  33428. ><TD
  33429. ><DIV
  33430. CLASS="example"
  33431. ><A
  33432. NAME="AEN5638"
  33433. ></A
  33434. ><P
  33435. ><B
  33436. >Example 19-23. Factory Method</B
  33437. ></P
  33438. ><TABLE
  33439. BORDER="0"
  33440. BGCOLOR="#E0E0E0"
  33441. CELLPADDING="5"
  33442. ><TR
  33443. ><TD
  33444. ><PRE
  33445. CLASS="php"
  33446. ><?php
  33447. class Example
  33448. {
  33449.     // The factory method
  33450.     function &factory($type)
  33451.     {
  33452.         if (include_once 'Drivers/' . $type . '.php') {
  33453.             $classname = 'Driver_' . $type;
  33454.             return new $classname;
  33455.         } else {
  33456.             throw new Exception ('Driver not found');
  33457.         }
  33458.     }
  33459. }
  33460. ?></PRE
  33461. ></TD
  33462. ></TR
  33463. ></TABLE
  33464. ><P
  33465. >     Defining this method in a class allows drivers to be loaded on the
  33466.     fly. If the <VAR
  33467. CLASS="literal"
  33468. >Example</VAR
  33469. > class was a database
  33470.     abstraction class, loading a <VAR
  33471. CLASS="literal"
  33472. >MySQL</VAR
  33473. > and
  33474.     <VAR
  33475. CLASS="literal"
  33476. >SQLite</VAR
  33477. > driver could be done as follows:
  33478.    </P
  33479. ><TABLE
  33480. BORDER="0"
  33481. BGCOLOR="#E0E0E0"
  33482. CELLPADDING="5"
  33483. ><TR
  33484. ><TD
  33485. ><PRE
  33486. CLASS="php"
  33487. ><?php
  33488. // Load a MySQL Driver
  33489. $mysql = Example::factory('MySQL');
  33490.  
  33491. // Load a SQLite Driver
  33492. $sqlite = Example::factory('SQLite');
  33493. ?></PRE
  33494. ></TD
  33495. ></TR
  33496. ></TABLE
  33497. ></DIV
  33498. ></TD
  33499. ></TR
  33500. ></TABLE
  33501. ></DIV
  33502. ><DIV
  33503. CLASS="sect2"
  33504. ><HR><H3
  33505. CLASS="sect2"
  33506. ><A
  33507. NAME="language.oop5.patterns.singleton"
  33508. >Singleton</A
  33509. ></H3
  33510. ><P
  33511. >    The Singleton pattern applies to situations in which
  33512.    there needs to be a single instance of a class.
  33513.    The most common example of this is a database connection.
  33514.    Implementing this pattern allows a programmer to make this
  33515.    single instance easily accessible by many other objects.
  33516.   </P
  33517. ><TABLE
  33518. WIDTH="100%"
  33519. BORDER="0"
  33520. CELLPADDING="0"
  33521. CELLSPACING="0"
  33522. CLASS="EXAMPLE"
  33523. ><TR
  33524. ><TD
  33525. ><DIV
  33526. CLASS="example"
  33527. ><A
  33528. NAME="AEN5649"
  33529. ></A
  33530. ><P
  33531. ><B
  33532. >Example 19-24. Singleton Function</B
  33533. ></P
  33534. ><TABLE
  33535. BORDER="0"
  33536. BGCOLOR="#E0E0E0"
  33537. CELLPADDING="5"
  33538. ><TR
  33539. ><TD
  33540. ><PRE
  33541. CLASS="php"
  33542. ><?php
  33543. class Example
  33544. {
  33545.     // Hold an instance of the class
  33546.     static private $instance;
  33547.     
  33548.     // A private constructor
  33549.     private function __construct() 
  33550.     {
  33551.         echo 'I am constructed';
  33552.     }
  33553.  
  33554.     // The singleton method
  33555.     static public function singleton() 
  33556.     {
  33557.         if (!isset(self::$instance)) {
  33558.             $c = __CLASS__;
  33559.             self::$instance = new $c;
  33560.         }
  33561.  
  33562.         return self::$instance;
  33563.     }
  33564.     
  33565.     // Example method
  33566.     public function bark()
  33567.     {
  33568.         echo 'Woof!';
  33569.     }
  33570. }
  33571.  
  33572. ?></PRE
  33573. ></TD
  33574. ></TR
  33575. ></TABLE
  33576. ><P
  33577. >     This allows a single instance of the <VAR
  33578. CLASS="literal"
  33579. >Example</VAR
  33580. >
  33581.     class to be retrieved.
  33582.    </P
  33583. ><TABLE
  33584. BORDER="0"
  33585. BGCOLOR="#E0E0E0"
  33586. CELLPADDING="5"
  33587. ><TR
  33588. ><TD
  33589. ><PRE
  33590. CLASS="php"
  33591. ><?php
  33592. // This would fail because the constructor is private
  33593. $test = new Example;
  33594.  
  33595. // This will always retrieve a single instance of the class
  33596. $test = Example::singleton();
  33597. $test->bark();
  33598.  
  33599. ?></PRE
  33600. ></TD
  33601. ></TR
  33602. ></TABLE
  33603. ></DIV
  33604. ></TD
  33605. ></TR
  33606. ></TABLE
  33607. ></DIV
  33608. ></DIV
  33609. ><DIV
  33610. CLASS="sect1"
  33611. ><HR><H2
  33612. CLASS="sect1"
  33613. ><A
  33614. NAME="language.oop5.magic"
  33615. >Magic Methods</A
  33616. ></H2
  33617. ><P
  33618. >    The function names
  33619.    <VAR
  33620. CLASS="literal"
  33621. >__construct</VAR
  33622. >,
  33623.    <VAR
  33624. CLASS="literal"
  33625. >__destruct</VAR
  33626. >
  33627.    (see <A
  33628. HREF="#language.oop5.decon"
  33629. >Constructors and Destructors</A
  33630. >),
  33631.    <VAR
  33632. CLASS="literal"
  33633. >__call</VAR
  33634. >,
  33635.    <VAR
  33636. CLASS="literal"
  33637. >__get</VAR
  33638. >,
  33639.    <VAR
  33640. CLASS="literal"
  33641. >__set</VAR
  33642. >
  33643.    (see <A
  33644. HREF="#language.oop5.overloading"
  33645. >Overloading</A
  33646. >),
  33647.    <VAR
  33648. CLASS="literal"
  33649. >__sleep</VAR
  33650. >,
  33651.    <VAR
  33652. CLASS="literal"
  33653. >__wakeup</VAR
  33654. >, and
  33655.    <VAR
  33656. CLASS="literal"
  33657. >__toString</VAR
  33658. > 
  33659.    are magical in PHP classes. You
  33660.    cannot have functions with these names in any of your
  33661.    classes unless you want the magic functionality associated
  33662.    with them.
  33663.   </P
  33664. ><DIV
  33665. CLASS="caution"
  33666. ><P
  33667. ></P
  33668. ><TABLE
  33669. CLASS="caution"
  33670. BORDER="1"
  33671. WIDTH="100%"
  33672. ><TR
  33673. ><TD
  33674. ALIGN="CENTER"
  33675. ><B
  33676. >Caution</B
  33677. ></TD
  33678. ></TR
  33679. ><TR
  33680. ><TD
  33681. ALIGN="LEFT"
  33682. ><P
  33683. >     PHP reserves all function names starting with __ as magical.
  33684.     It is recommended that you do not use function names with
  33685.     __ in PHP unless you want some documented magic functionality.
  33686.    </P
  33687. ></TD
  33688. ></TR
  33689. ></TABLE
  33690. ></DIV
  33691. ><DIV
  33692. CLASS="sect2"
  33693. ><HR><H3
  33694. CLASS="sect2"
  33695. ><A
  33696. NAME="language.oop5.magic.sleep"
  33697. ><VAR
  33698. CLASS="literal"
  33699. >__sleep</VAR
  33700. > and <VAR
  33701. CLASS="literal"
  33702. >__wakeup</VAR
  33703. ></A
  33704. ></H3
  33705. ><P
  33706. >     <A
  33707. HREF="#function.serialize"
  33708. ><B
  33709. CLASS="function"
  33710. >serialize()</B
  33711. ></A
  33712. > checks if your class has a function with
  33713.     the magic name <VAR
  33714. CLASS="literal"
  33715. >__sleep</VAR
  33716. >. If so, that function is
  33717.     being run prior to any serialization. It can clean up the object
  33718.     and is supposed to return an array with the names of all variables
  33719.     of that object that should be serialized.
  33720.    </P
  33721. ><P
  33722. >     The intended use of <VAR
  33723. CLASS="literal"
  33724. >__sleep</VAR
  33725. > is to close any
  33726.     database connections that object may have, committing pending
  33727.     data or perform similar cleanup tasks. Also, the function is
  33728.     useful if you have very large objects which need not be
  33729.     saved completely.
  33730.    </P
  33731. ><P
  33732. >     Conversely, <A
  33733. HREF="#function.unserialize"
  33734. ><B
  33735. CLASS="function"
  33736. >unserialize()</B
  33737. ></A
  33738. > checks for the
  33739.     presence of a function with the magic name 
  33740.     <VAR
  33741. CLASS="literal"
  33742. >__wakeup</VAR
  33743. >. If present, this function can
  33744.     reconstruct any resources that object may have.
  33745.    </P
  33746. ><P
  33747. >     The intended use of <VAR
  33748. CLASS="literal"
  33749. >__wakeup</VAR
  33750. > is to
  33751.     reestablish any database connections that may have been lost
  33752.     during serialization and perform other reinitialization
  33753.     tasks.
  33754.    </P
  33755. ></DIV
  33756. ><DIV
  33757. CLASS="sect2"
  33758. ><HR><H3
  33759. CLASS="sect2"
  33760. ><A
  33761. NAME="language.oop5.magic.tostring"
  33762. ><VAR
  33763. CLASS="literal"
  33764. >__toString</VAR
  33765. ></A
  33766. ></H3
  33767. ><P
  33768. >     The <VAR
  33769. CLASS="literal"
  33770. >__toString</VAR
  33771. > method allows a class to decide
  33772.     how it will react when it is converted to a string.
  33773.    </P
  33774. ><TABLE
  33775. WIDTH="100%"
  33776. BORDER="0"
  33777. CELLPADDING="0"
  33778. CELLSPACING="0"
  33779. CLASS="EXAMPLE"
  33780. ><TR
  33781. ><TD
  33782. ><DIV
  33783. CLASS="example"
  33784. ><A
  33785. NAME="AEN5689"
  33786. ></A
  33787. ><P
  33788. ><B
  33789. >Example 19-25. Simple example</B
  33790. ></P
  33791. ><TABLE
  33792. BORDER="0"
  33793. BGCOLOR="#E0E0E0"
  33794. CELLPADDING="5"
  33795. ><TR
  33796. ><TD
  33797. ><PRE
  33798. CLASS="php"
  33799. ><?php
  33800. // Declare a simple class
  33801. class TestClass
  33802. {
  33803.     public $foo;
  33804.  
  33805.     public function __construct($foo) {
  33806.         $this->foo = $foo;
  33807.     }
  33808.  
  33809.     public function __toString() {
  33810.         return $this->foo;
  33811.     }
  33812. }
  33813.  
  33814. $class = new TestClass('Hello');
  33815. echo $class;
  33816. ?></PRE
  33817. ></TD
  33818. ></TR
  33819. ></TABLE
  33820. ><P
  33821. >The above example will output:</P
  33822. ><TABLE
  33823. BORDER="0"
  33824. BGCOLOR="#E0E0E0"
  33825. CELLPADDING="5"
  33826. ><TR
  33827. ><TD
  33828. ><PRE
  33829. CLASS="screen"
  33830. >Hello</PRE
  33831. ></TD
  33832. ></TR
  33833. ></TABLE
  33834. ></DIV
  33835. ></TD
  33836. ></TR
  33837. ></TABLE
  33838. ><P
  33839. >     It is worth noting that the <VAR
  33840. CLASS="literal"
  33841. >__toString</VAR
  33842. > method
  33843.     will only be called when it is directly combined with
  33844.     <A
  33845. HREF="#function.echo"
  33846. ><B
  33847. CLASS="function"
  33848. >echo()</B
  33849. ></A
  33850. > or <A
  33851. HREF="#function.print"
  33852. ><B
  33853. CLASS="function"
  33854. >print()</B
  33855. ></A
  33856. >.
  33857.    </P
  33858. ><TABLE
  33859. WIDTH="100%"
  33860. BORDER="0"
  33861. CELLPADDING="0"
  33862. CELLSPACING="0"
  33863. CLASS="EXAMPLE"
  33864. ><TR
  33865. ><TD
  33866. ><DIV
  33867. CLASS="example"
  33868. ><A
  33869. NAME="AEN5698"
  33870. ></A
  33871. ><P
  33872. ><B
  33873. >Example 19-26. Cases where <VAR
  33874. CLASS="literal"
  33875. >__toString</VAR
  33876. > is called</B
  33877. ></P
  33878. ><TABLE
  33879. BORDER="0"
  33880. BGCOLOR="#E0E0E0"
  33881. CELLPADDING="5"
  33882. ><TR
  33883. ><TD
  33884. ><PRE
  33885. CLASS="php"
  33886. ><?php
  33887. // __toString called
  33888. echo $class;
  33889.  
  33890. // __toString called (still a normal parameter for echo)
  33891. echo 'text', $class;
  33892.  
  33893. // __toString not called (concatenation operator used first)
  33894. echo 'text' . $class;
  33895.  
  33896. // __toString not called (cast to string first)
  33897. echo (string) $class;
  33898.  
  33899. // __toString not called (cast to string first)
  33900. echo "text $class";
  33901. ?></PRE
  33902. ></TD
  33903. ></TR
  33904. ></TABLE
  33905. ></DIV
  33906. ></TD
  33907. ></TR
  33908. ></TABLE
  33909. ></DIV
  33910. ></DIV
  33911. ><DIV
  33912. CLASS="sect1"
  33913. ><HR><H2
  33914. CLASS="sect1"
  33915. ><A
  33916. NAME="language.oop5.final"
  33917. >Final Keyword</A
  33918. ></H2
  33919. ><P
  33920. >    PHP 5 introduces the final keyword, which prevents child classes from
  33921.    overriding a method by prefixing the definition with final. If the class
  33922.    itself is being defined final then it cannot be extended.
  33923.   </P
  33924. ><TABLE
  33925. WIDTH="100%"
  33926. BORDER="0"
  33927. CELLPADDING="0"
  33928. CELLSPACING="0"
  33929. CLASS="EXAMPLE"
  33930. ><TR
  33931. ><TD
  33932. ><DIV
  33933. CLASS="example"
  33934. ><A
  33935. NAME="AEN5705"
  33936. ></A
  33937. ><P
  33938. ><B
  33939. >Example 19-27. Final methods example</B
  33940. ></P
  33941. ><TABLE
  33942. BORDER="0"
  33943. BGCOLOR="#E0E0E0"
  33944. CELLPADDING="5"
  33945. ><TR
  33946. ><TD
  33947. ><PRE
  33948. CLASS="php"
  33949. ><?php
  33950. class BaseClass {
  33951.    public function test() {
  33952.        echo "BaseClass::test() called\n";
  33953.    }
  33954.    
  33955.    final public function moreTesting() {
  33956.        echo "BaseClass::moreTesting() called\n";
  33957.    }
  33958. }
  33959.  
  33960. class ChildClass extends BaseClass {
  33961.    public function moreTesting() {
  33962.        echo "ChildClass::moreTesting() called\n";
  33963.    }
  33964. }
  33965. // Results in Fatal error: Cannot override final method BaseClass::moreTesting()
  33966. ?></PRE
  33967. ></TD
  33968. ></TR
  33969. ></TABLE
  33970. ></DIV
  33971. ></TD
  33972. ></TR
  33973. ></TABLE
  33974. ><TABLE
  33975. WIDTH="100%"
  33976. BORDER="0"
  33977. CELLPADDING="0"
  33978. CELLSPACING="0"
  33979. CLASS="EXAMPLE"
  33980. ><TR
  33981. ><TD
  33982. ><DIV
  33983. CLASS="example"
  33984. ><A
  33985. NAME="AEN5708"
  33986. ></A
  33987. ><P
  33988. ><B
  33989. >Example 19-28. Final class example</B
  33990. ></P
  33991. ><TABLE
  33992. BORDER="0"
  33993. BGCOLOR="#E0E0E0"
  33994. CELLPADDING="5"
  33995. ><TR
  33996. ><TD
  33997. ><PRE
  33998. CLASS="php"
  33999. ><?php
  34000. final class BaseClass {
  34001.    public function test() {
  34002.        echo "BaseClass::test() called\n";
  34003.    }
  34004.  
  34005.    // Here it doesn't matter if you specify the function as final or not
  34006.    final public function moreTesting() {
  34007.        echo "BaseClass::moreTesting() called\n";
  34008.    }
  34009. }
  34010.  
  34011. class ChildClass extends BaseClass {
  34012. }
  34013. // Results in Fatal error: Class ChildClass may not inherit from final class (BaseClass)
  34014. ?></PRE
  34015. ></TD
  34016. ></TR
  34017. ></TABLE
  34018. ></DIV
  34019. ></TD
  34020. ></TR
  34021. ></TABLE
  34022. ></DIV
  34023. ><DIV
  34024. CLASS="sect1"
  34025. ><HR><H2
  34026. CLASS="sect1"
  34027. ><A
  34028. NAME="language.oop5.cloning"
  34029. >Object cloning</A
  34030. ></H2
  34031. ><P
  34032. >    Creating a copy of an object with fully replicated properties is not
  34033.    always the wanted behavior. A good example of the need for copy
  34034.    constructors, is if you have an object which represents a GTK window and the
  34035.    object holds the resource of this GTK window, when you create a duplicate
  34036.    you might want to create a new window with the same properties and have the
  34037.    new object hold the resource of the new window. Another example is if your
  34038.    object holds a reference to another object which it uses and when you
  34039.    replicate the parent object you want to create a new instance of this other
  34040.    object so that the replica has its own separate copy.
  34041.   </P
  34042. ><P
  34043. >    An object copy is created by using the clone keyword (which calls the
  34044.    object's __clone() method if possible). An object's __clone()  method
  34045.    cannot be called directly.
  34046.   </P
  34047. ><DIV
  34048. CLASS="informalexample"
  34049. ><P
  34050. ></P
  34051. ><A
  34052. NAME="AEN5715"
  34053. ></A
  34054. ><TABLE
  34055. BORDER="0"
  34056. BGCOLOR="#E0E0E0"
  34057. CELLPADDING="5"
  34058. ><TR
  34059. ><TD
  34060. ><PRE
  34061. CLASS="programlisting"
  34062. >$copy_of_object = clone $object;</PRE
  34063. ></TD
  34064. ></TR
  34065. ></TABLE
  34066. ><P
  34067. ></P
  34068. ></DIV
  34069. ><P
  34070. >    When an object is cloned, PHP 5 will perform a shallow copy of all of the
  34071.    object's properties. Any properties that are references to other variables,
  34072.    will remain references. If a __clone() method is defined, then the newly
  34073.    created  object's __clone() method will be called, to allow any necessary
  34074.    properties that need to be changed.
  34075.   </P
  34076. ><TABLE
  34077. WIDTH="100%"
  34078. BORDER="0"
  34079. CELLPADDING="0"
  34080. CELLSPACING="0"
  34081. CLASS="EXAMPLE"
  34082. ><TR
  34083. ><TD
  34084. ><DIV
  34085. CLASS="example"
  34086. ><A
  34087. NAME="AEN5718"
  34088. ></A
  34089. ><P
  34090. ><B
  34091. >Example 19-29. Cloning an object</B
  34092. ></P
  34093. ><TABLE
  34094. BORDER="0"
  34095. BGCOLOR="#E0E0E0"
  34096. CELLPADDING="5"
  34097. ><TR
  34098. ><TD
  34099. ><PRE
  34100. CLASS="php"
  34101. ><?php
  34102. class SubObject
  34103. {
  34104.     static $instances = 0;
  34105.     public $instance;
  34106.  
  34107.     public function __construct() {
  34108.         $this->instance = ++self::$instances;
  34109.     }
  34110.  
  34111.     public function __clone() {
  34112.         $this->instance = ++self::$instances;
  34113.     }
  34114. }
  34115.  
  34116. class MyCloneable
  34117. {
  34118.     public $object1;
  34119.     public $object2;
  34120.  
  34121.     function __clone()
  34122.     {
  34123.         // Force a copy of this->object, otherwise
  34124.         // it will point to same object.
  34125.         $this->object1 = clone($this->object1);
  34126.     }
  34127. }
  34128.  
  34129. $obj = new MyCloneable();
  34130.  
  34131. $obj->object1 = new SubObject();
  34132. $obj->object2 = new SubObject();
  34133.  
  34134. $obj2 = clone $obj;
  34135.  
  34136.  
  34137. print("Original Object:\n");
  34138. print_r($obj);
  34139.  
  34140. print("Cloned Object:\n");
  34141. print_r($obj2);
  34142.  
  34143. ?></PRE
  34144. ></TD
  34145. ></TR
  34146. ></TABLE
  34147. ><P
  34148. >The above example will output:</P
  34149. ><TABLE
  34150. BORDER="0"
  34151. BGCOLOR="#E0E0E0"
  34152. CELLPADDING="5"
  34153. ><TR
  34154. ><TD
  34155. ><PRE
  34156. CLASS="php"
  34157. >Original Object:
  34158. MyCloneable Object
  34159. (
  34160.     [object1] => SubObject Object
  34161.         (
  34162.             [instance] => 1
  34163.         )
  34164.  
  34165.     [object2] => SubObject Object
  34166.         (
  34167.             [instance] => 2
  34168.         )
  34169.  
  34170. )
  34171. Cloned Object:
  34172. MyCloneable Object
  34173. (
  34174.     [object1] => SubObject Object
  34175.         (
  34176.             [instance] => 3
  34177.         )
  34178.  
  34179.     [object2] => SubObject Object
  34180.         (
  34181.             [instance] => 2
  34182.         )
  34183.  
  34184. )</PRE
  34185. ></TD
  34186. ></TR
  34187. ></TABLE
  34188. ></DIV
  34189. ></TD
  34190. ></TR
  34191. ></TABLE
  34192. ></DIV
  34193. ><DIV
  34194. CLASS="sect1"
  34195. ><HR><H2
  34196. CLASS="sect1"
  34197. ><A
  34198. NAME="language.oop5.object-comparison"
  34199. >Comparing objects</A
  34200. ></H2
  34201. ><P
  34202. >     In PHP 5, object comparison is more complicated than in PHP 4 and more
  34203.     in accordance to what one will expect from an Object Oriented Language
  34204.     (not that PHP 5 is such a language).
  34205.    </P
  34206. ><P
  34207. >     When using the comparison operator (<VAR
  34208. CLASS="literal"
  34209. >==</VAR
  34210. >), 
  34211.     object variables are compared in a simple manner, namely: Two object
  34212.     instances are equal if they have the same attributes and values, and are
  34213.     instances of the same class.
  34214.    </P
  34215. ><P
  34216. >     On the other hand, when using the identity operator (<VAR
  34217. CLASS="literal"
  34218. >===</VAR
  34219. >),
  34220.     object variables are identical if and only if they refer to the same
  34221.     instance of the same class.
  34222.    </P
  34223. ><P
  34224. >     An example will clarify these rules.
  34225.     <TABLE
  34226. WIDTH="100%"
  34227. BORDER="0"
  34228. CELLPADDING="0"
  34229. CELLSPACING="0"
  34230. CLASS="EXAMPLE"
  34231. ><TR
  34232. ><TD
  34233. ><DIV
  34234. CLASS="example"
  34235. ><A
  34236. NAME="AEN5731"
  34237. ></A
  34238. ><P
  34239. ><B
  34240. >Example 19-30. Example of object comparison in PHP 5</B
  34241. ></P
  34242. ><TABLE
  34243. BORDER="0"
  34244. BGCOLOR="#E0E0E0"
  34245. CELLPADDING="5"
  34246. ><TR
  34247. ><TD
  34248. ><PRE
  34249. CLASS="php"
  34250. ><?php
  34251. function bool2str($bool)
  34252. {
  34253.     if ($bool === false) {
  34254.         return 'FALSE';
  34255.     } else {
  34256.         return 'TRUE';
  34257.     }
  34258. }
  34259.  
  34260. function compareObjects(&$o1, &$o2)
  34261. {
  34262.     echo 'o1 == o2 : ' . bool2str($o1 == $o2) . "\n";
  34263.     echo 'o1 != o2 : ' . bool2str($o1 != $o2) . "\n";
  34264.     echo 'o1 === o2 : ' . bool2str($o1 === $o2) . "\n";
  34265.     echo 'o1 !== o2 : ' . bool2str($o1 !== $o2) . "\n";
  34266. }
  34267.  
  34268. class Flag
  34269. {
  34270.     public $flag;
  34271.  
  34272.     function Flag($flag = true) {
  34273.         $this->flag = $flag;
  34274.     }
  34275. }
  34276.  
  34277. class OtherFlag
  34278. {
  34279.     public $flag;
  34280.  
  34281.     function OtherFlag($flag = true) {
  34282.         $this->flag = $flag;
  34283.     }
  34284. }
  34285.  
  34286. $o = new Flag();
  34287. $p = new Flag();
  34288. $q = $o;
  34289. $r = new OtherFlag();
  34290.  
  34291. echo "Two instances of the same class\n";
  34292. compareObjects($o, $p);
  34293.  
  34294. echo "\nTwo references to the same instance\n";
  34295. compareObjects($o, $q);
  34296.  
  34297. echo "\nInstances of two different classes\n";
  34298. compareObjects($o, $r);
  34299. ?></PRE
  34300. ></TD
  34301. ></TR
  34302. ></TABLE
  34303. ></DIV
  34304. ></TD
  34305. ></TR
  34306. ></TABLE
  34307. >
  34308.     This example will output:
  34309.     <TABLE
  34310. BORDER="0"
  34311. BGCOLOR="#E0E0E0"
  34312. CELLPADDING="5"
  34313. ><TR
  34314. ><TD
  34315. ><PRE
  34316. CLASS="screen"
  34317. >Two instances of the same class
  34318. o1 == o2 : TRUE
  34319. o1 != o2 : FALSE
  34320. o1 === o2 : FALSE
  34321. o1 !== o2 : TRUE
  34322.  
  34323. Two references to the same instance
  34324. o1 == o2 : TRUE
  34325. o1 != o2 : FALSE
  34326. o1 === o2 : TRUE
  34327. o1 !== o2 : FALSE
  34328.  
  34329. Instances of two different classes
  34330. o1 == o2 : FALSE
  34331. o1 != o2 : TRUE
  34332. o1 === o2 : FALSE
  34333. o1 !== o2 : TRUE</PRE
  34334. ></TD
  34335. ></TR
  34336. ></TABLE
  34337. >
  34338.    </P
  34339. ></DIV
  34340. ><DIV
  34341. CLASS="sect1"
  34342. ><HR><H2
  34343. CLASS="sect1"
  34344. ><A
  34345. NAME="language.oop5.reflection"
  34346. >Reflection</A
  34347. ></H2
  34348. ><DIV
  34349. CLASS="sect2"
  34350. ><H3
  34351. CLASS="sect2"
  34352. ><A
  34353. NAME="language.oop5.reflection.introduction"
  34354. >Introduction</A
  34355. ></H3
  34356. ><P
  34357. >     PHP 5 comes with a complete reflection API that adds the ability to
  34358.     reverse-engineer classes, interfaces, functions and methods as well
  34359.     as extensions. Additionally, the reflection API also offers ways of 
  34360.     retrieving doc comments for functions, classes and methods.
  34361.    </P
  34362. ><P
  34363. >     The reflection API is an object-oriented extension to the Zend Engine,
  34364.     consisting of the following classes:
  34365.    </P
  34366. ><DIV
  34367. CLASS="informalexample"
  34368. ><P
  34369. ></P
  34370. ><A
  34371. NAME="AEN5741"
  34372. ></A
  34373. ><TABLE
  34374. BORDER="0"
  34375. BGCOLOR="#E0E0E0"
  34376. CELLPADDING="5"
  34377. ><TR
  34378. ><TD
  34379. ><PRE
  34380. CLASS="php"
  34381. ><?php
  34382. class Reflection { }
  34383. interface Reflector { }
  34384. class ReflectionException extends Exception { }
  34385. class ReflectionFunction implements Reflector { }
  34386. class ReflectionParameter implements Reflector { }
  34387. class ReflectionMethod extends ReflectionFunction { }
  34388. class ReflectionClass implements Reflector { }
  34389. class ReflectionObject extends ReflectionClass { }
  34390. class ReflectionProperty implements Reflector { }
  34391. class ReflectionExtension implements Reflector { }
  34392. ?></PRE
  34393. ></TD
  34394. ></TR
  34395. ></TABLE
  34396. ><P
  34397. ></P
  34398. ></DIV
  34399. ><DIV
  34400. CLASS="note"
  34401. ><BLOCKQUOTE
  34402. CLASS="note"
  34403. ><P
  34404. ><B
  34405. >Note: </B
  34406. >
  34407.      For details on these classes, have a look at the next chapters.
  34408.     </P
  34409. ></BLOCKQUOTE
  34410. ></DIV
  34411. ><P
  34412. >     If we were to execute the code in the example below:
  34413.     <TABLE
  34414. WIDTH="100%"
  34415. BORDER="0"
  34416. CELLPADDING="0"
  34417. CELLSPACING="0"
  34418. CLASS="EXAMPLE"
  34419. ><TR
  34420. ><TD
  34421. ><DIV
  34422. CLASS="example"
  34423. ><A
  34424. NAME="AEN5746"
  34425. ></A
  34426. ><P
  34427. ><B
  34428. >Example 19-31. Basic usage of the reflection API</B
  34429. ></P
  34430. ><TABLE
  34431. BORDER="0"
  34432. BGCOLOR="#E0E0E0"
  34433. CELLPADDING="5"
  34434. ><TR
  34435. ><TD
  34436. ><PRE
  34437. CLASS="php"
  34438. ><?php
  34439. Reflection::export(new ReflectionClass('Exception'));
  34440. ?></PRE
  34441. ></TD
  34442. ></TR
  34443. ></TABLE
  34444. ><P
  34445. >The above example will output:</P
  34446. ><TABLE
  34447. BORDER="0"
  34448. BGCOLOR="#E0E0E0"
  34449. CELLPADDING="5"
  34450. ><TR
  34451. ><TD
  34452. ><PRE
  34453. CLASS="screen"
  34454. >Class [ <internal> class Exception ] {
  34455.  
  34456.   - Constants [0] {
  34457.   }
  34458.  
  34459.   - Static properties [0] {
  34460.   }
  34461.  
  34462.   - Static methods [0] {
  34463.   }
  34464.  
  34465.   - Properties [6] {
  34466.     Property [ <default> protected $message ]
  34467.     Property [ <default> private $string ]
  34468.     Property [ <default> protected $code ]
  34469.     Property [ <default> protected $file ]
  34470.     Property [ <default> protected $line ]
  34471.     Property [ <default> private $trace ]
  34472.   }
  34473.  
  34474.   - Methods [9] {
  34475.     Method [ <internal> final private method __clone ] {
  34476.     }
  34477.  
  34478.     Method [ <internal> <ctor> public method __construct ] {
  34479.  
  34480.       - Parameters [2] {
  34481.         Parameter #0 [ <required> $message ]
  34482.         Parameter #1 [ <required> $code ]
  34483.       }
  34484.     }
  34485.  
  34486.     Method [ <internal> final public method getMessage ] {
  34487.     }
  34488.  
  34489.     Method [ <internal> final public method getCode ] {
  34490.     }
  34491.  
  34492.     Method [ <internal> final public method getFile ] {
  34493.     }
  34494.  
  34495.     Method [ <internal> final public method getLine ] {
  34496.     }
  34497.  
  34498.     Method [ <internal> final public method getTrace ] {
  34499.     }
  34500.  
  34501.     Method [ <internal> final public method getTraceAsString ] {
  34502.     }
  34503.  
  34504.     Method [ <internal> public method __toString ] {
  34505.     }
  34506.   }
  34507. }</PRE
  34508. ></TD
  34509. ></TR
  34510. ></TABLE
  34511. ></DIV
  34512. ></TD
  34513. ></TR
  34514. ></TABLE
  34515. >
  34516.    </P
  34517. ></DIV
  34518. ><DIV
  34519. CLASS="sect2"
  34520. ><HR><H3
  34521. CLASS="sect2"
  34522. ><A
  34523. NAME="language.oop5.reflection.reflectionfunction"
  34524. ><B
  34525. CLASS="classname"
  34526. >ReflectionFunction</B
  34527. ></A
  34528. ></H3
  34529. ><P
  34530. >     The <B
  34531. CLASS="classname"
  34532. >ReflectionFunction</B
  34533. > class lets you
  34534.     reverse-engineer functions.
  34535.    </P
  34536. ><DIV
  34537. CLASS="informalexample"
  34538. ><P
  34539. ></P
  34540. ><A
  34541. NAME="AEN5756"
  34542. ></A
  34543. ><TABLE
  34544. BORDER="0"
  34545. BGCOLOR="#E0E0E0"
  34546. CELLPADDING="5"
  34547. ><TR
  34548. ><TD
  34549. ><PRE
  34550. CLASS="php"
  34551. ><?php
  34552. class ReflectionFunction implements Reflector
  34553. {
  34554.     final private __clone()
  34555.     public object __construct(string name)
  34556.     public string __toString()
  34557.     public static string export()
  34558.     public string getName()
  34559.     public bool isInternal()
  34560.     public bool isUserDefined()
  34561.     public string getFileName()
  34562.     public int getStartLine()
  34563.     public int getEndLine()
  34564.     public string getDocComment()
  34565.     public array getStaticVariables()
  34566.     public mixed invoke(mixed* args)
  34567.     public mixed invokeArgs(array args)
  34568.     public bool returnsReference()
  34569.     public ReflectionParameter[] getParameters()
  34570.     public int getNumberOfParameters()
  34571.     public int getNumberOfRequiredParameters()
  34572. }
  34573. ?></PRE
  34574. ></TD
  34575. ></TR
  34576. ></TABLE
  34577. ><P
  34578. ></P
  34579. ></DIV
  34580. ><DIV
  34581. CLASS="note"
  34582. ><BLOCKQUOTE
  34583. CLASS="note"
  34584. ><P
  34585. ><B
  34586. >Note: </B
  34587. >
  34588.      <B
  34589. CLASS="function"
  34590. >invokeArgs()</B
  34591. > was added in PHP 5.1.0.
  34592.     </P
  34593. ></BLOCKQUOTE
  34594. ></DIV
  34595. ><P
  34596. >     To introspect a function, you will first have to create an instance
  34597.     of the <B
  34598. CLASS="classname"
  34599. >ReflectionFunction</B
  34600. > class. You can then call
  34601.     any of the above methods on this instance.
  34602.    </P
  34603. ><TABLE
  34604. WIDTH="100%"
  34605. BORDER="0"
  34606. CELLPADDING="0"
  34607. CELLSPACING="0"
  34608. CLASS="EXAMPLE"
  34609. ><TR
  34610. ><TD
  34611. ><DIV
  34612. CLASS="example"
  34613. ><A
  34614. NAME="AEN5763"
  34615. ></A
  34616. ><P
  34617. ><B
  34618. >Example 19-32. Using the <B
  34619. CLASS="classname"
  34620. >ReflectionFunction</B
  34621. > class</B
  34622. ></P
  34623. ><TABLE
  34624. BORDER="0"
  34625. BGCOLOR="#E0E0E0"
  34626. CELLPADDING="5"
  34627. ><TR
  34628. ><TD
  34629. ><PRE
  34630. CLASS="php"
  34631. ><?php
  34632. /**
  34633.  * A simple counter
  34634.  *
  34635.  * @return    int
  34636.  */
  34637. function counter() 
  34638. {
  34639.     static $c = 0;
  34640.     return $c++;
  34641. }
  34642.  
  34643. // Create an instance of the Reflection_Function class
  34644. $func = new ReflectionFunction('counter');
  34645.  
  34646. // Print out basic information
  34647. printf(
  34648.     "===> The %s function '%s'\n".
  34649.     "     declared in %s\n".
  34650.     "     lines %d to %d\n",
  34651.     $func->isInternal() ? 'internal' : 'user-defined',
  34652.     $func->getName(),
  34653.     $func->getFileName(),
  34654.     $func->getStartLine(),
  34655.     $func->getEndline()
  34656. );
  34657.  
  34658. // Print documentation comment
  34659. printf("---> Documentation:\n %s\n", var_export($func->getDocComment(), 1));
  34660.  
  34661. // Print static variables if existant
  34662. if ($statics = $func->getStaticVariables())
  34663. {
  34664.     printf("---> Static variables: %s\n", var_export($statics, 1));
  34665. }
  34666.  
  34667. // Invoke the function
  34668. printf("---> Invokation results in: ");
  34669. var_dump($func->invoke());
  34670.  
  34671.  
  34672. // you may prefer to use the export() method
  34673. echo "\nReflectionFunction::export() results:\n";
  34674. echo ReflectionFunction::export('counter');
  34675. ?></PRE
  34676. ></TD
  34677. ></TR
  34678. ></TABLE
  34679. ></DIV
  34680. ></TD
  34681. ></TR
  34682. ></TABLE
  34683. ><DIV
  34684. CLASS="note"
  34685. ><BLOCKQUOTE
  34686. CLASS="note"
  34687. ><P
  34688. ><B
  34689. >Note: </B
  34690. >
  34691.      The method <B
  34692. CLASS="function"
  34693. >invoke()</B
  34694. > accepts a variable number of
  34695.      arguments which are passed to the function just as in
  34696.      <A
  34697. HREF="#function.call-user-func"
  34698. ><B
  34699. CLASS="function"
  34700. >call_user_func()</B
  34701. ></A
  34702. >.
  34703.     </P
  34704. ></BLOCKQUOTE
  34705. ></DIV
  34706. ></DIV
  34707. ><DIV
  34708. CLASS="sect2"
  34709. ><HR><H3
  34710. CLASS="sect2"
  34711. ><A
  34712. NAME="language.oop5.reflection.reflectionparameter"
  34713. ><B
  34714. CLASS="classname"
  34715. >ReflectionParameter</B
  34716. ></A
  34717. ></H3
  34718. ><P
  34719. >     The <B
  34720. CLASS="classname"
  34721. >ReflectionParameter</B
  34722. > class retrieves
  34723.     information about a function's or method's parameters.
  34724.    </P
  34725. ><DIV
  34726. CLASS="informalexample"
  34727. ><P
  34728. ></P
  34729. ><A
  34730. NAME="AEN5776"
  34731. ></A
  34732. ><TABLE
  34733. BORDER="0"
  34734. BGCOLOR="#E0E0E0"
  34735. CELLPADDING="5"
  34736. ><TR
  34737. ><TD
  34738. ><PRE
  34739. CLASS="php"
  34740. ><?php
  34741. class ReflectionParameter implements Reflector
  34742. {
  34743.     final private __clone()
  34744.     public object __construct(string name)
  34745.     public string __toString()
  34746.     public static string export()
  34747.     public string getName()
  34748.     public bool isPassedByReference()
  34749.     public ReflectionClass getClass()
  34750.     public bool allowsNull()
  34751.     public bool isOptional()
  34752.     public bool isDefaultValueAvailable()
  34753.     public mixed getDefaultValue()
  34754. }
  34755. ?></PRE
  34756. ></TD
  34757. ></TR
  34758. ></TABLE
  34759. ><P
  34760. ></P
  34761. ></DIV
  34762. ><DIV
  34763. CLASS="note"
  34764. ><BLOCKQUOTE
  34765. CLASS="note"
  34766. ><P
  34767. ><B
  34768. >Note: </B
  34769. >
  34770.      <B
  34771. CLASS="function"
  34772. >getDefaultValue()</B
  34773. >,
  34774.      <B
  34775. CLASS="function"
  34776. >isDefaultValueAvailable()</B
  34777. >,
  34778.      <B
  34779. CLASS="function"
  34780. >isOptional()</B
  34781. > were added in PHP 5.1.0.
  34782.     </P
  34783. ></BLOCKQUOTE
  34784. ></DIV
  34785. ><P
  34786. >     To introspect function parameters, you will first have to create an instance
  34787.     of the <B
  34788. CLASS="classname"
  34789. >ReflectionFunction</B
  34790. > or 
  34791.     <B
  34792. CLASS="classname"
  34793. >ReflectionMethod</B
  34794. > classes and then use their 
  34795.     <B
  34796. CLASS="function"
  34797. >getParameters()</B
  34798. > method to retrieve an array of parameters.
  34799.    </P
  34800. ><TABLE
  34801. WIDTH="100%"
  34802. BORDER="0"
  34803. CELLPADDING="0"
  34804. CELLSPACING="0"
  34805. CLASS="EXAMPLE"
  34806. ><TR
  34807. ><TD
  34808. ><DIV
  34809. CLASS="example"
  34810. ><A
  34811. NAME="AEN5787"
  34812. ></A
  34813. ><P
  34814. ><B
  34815. >Example 19-33. Using the <B
  34816. CLASS="classname"
  34817. >ReflectionParameter</B
  34818. > class</B
  34819. ></P
  34820. ><TABLE
  34821. BORDER="0"
  34822. BGCOLOR="#E0E0E0"
  34823. CELLPADDING="5"
  34824. ><TR
  34825. ><TD
  34826. ><PRE
  34827. CLASS="php"
  34828. ><?php
  34829. function foo($a, $b, $c) { }
  34830. function bar(Exception $a, &$b, $c) { }
  34831. function baz(ReflectionFunction $a, $b = 1, $c = null) { }
  34832. function abc() { }
  34833.  
  34834. // Create an instance of Reflection_Function with the
  34835. // parameter given from the command line.    
  34836. $reflect = new ReflectionFunction($argv[1]);
  34837.  
  34838. echo $reflect;
  34839.  
  34840. foreach ($reflect->getParameters() as $i => $param) {
  34841.     printf(
  34842.         "-- Parameter #%d: %s {\n".
  34843.         "   Class: %s\n".
  34844.         "   Allows NULL: %s\n".
  34845.         "   Passed to by reference: %s\n".
  34846.         "   Is optional?: %s\n".
  34847.         "}\n",
  34848.         $i, 
  34849.         $param->getName(),
  34850.         var_export($param->getClass(), 1),
  34851.         var_export($param->allowsNull(), 1),
  34852.         var_export($param->isPassedByReference(), 1),
  34853.         $param->isOptional() ? 'yes' : 'no'
  34854.     );
  34855. }
  34856. ?></PRE
  34857. ></TD
  34858. ></TR
  34859. ></TABLE
  34860. ></DIV
  34861. ></TD
  34862. ></TR
  34863. ></TABLE
  34864. ></DIV
  34865. ><DIV
  34866. CLASS="sect2"
  34867. ><HR><H3
  34868. CLASS="sect2"
  34869. ><A
  34870. NAME="language.oop5.reflection.reflectionclass"
  34871. ><B
  34872. CLASS="classname"
  34873. >ReflectionClass</B
  34874. ></A
  34875. ></H3
  34876. ><P
  34877. >     The <B
  34878. CLASS="classname"
  34879. >ReflectionClass</B
  34880. > class lets
  34881.     you reverse-engineer classes.
  34882.    </P
  34883. ><DIV
  34884. CLASS="informalexample"
  34885. ><P
  34886. ></P
  34887. ><A
  34888. NAME="AEN5796"
  34889. ></A
  34890. ><TABLE
  34891. BORDER="0"
  34892. BGCOLOR="#E0E0E0"
  34893. CELLPADDING="5"
  34894. ><TR
  34895. ><TD
  34896. ><PRE
  34897. CLASS="php"
  34898. ><?php
  34899. class ReflectionClass implements Reflector
  34900. {
  34901.     final private __clone()
  34902.     public object __construct(string name)
  34903.     public string __toString()
  34904.     public static string export()
  34905.     public string getName()
  34906.     public bool isInternal()
  34907.     public bool isUserDefined()
  34908.     public bool isInstantiable()
  34909.     public bool hasMethod(string name)
  34910.     public string getFileName()
  34911.     public int getStartLine()
  34912.     public int getEndLine()
  34913.     public string getDocComment()
  34914.     public ReflectionMethod getConstructor()
  34915.     public ReflectionMethod getMethod(string name)
  34916.     public ReflectionMethod[] getMethods()
  34917.     public ReflectionProperty getProperty(string name)
  34918.     public ReflectionProperty[] getProperties()
  34919.     public array getConstants()
  34920.     public mixed getConstant(string name)
  34921.     public ReflectionClass[] getInterfaces()
  34922.     public bool isInterface()
  34923.     public bool isAbstract()
  34924.     public bool isFinal()
  34925.     public int getModifiers()
  34926.     public bool isInstance(stdclass object)
  34927.     public stdclass newInstance(mixed* args)
  34928.     public ReflectionClass getParentClass()
  34929.     public bool isSubclassOf(ReflectionClass class)
  34930.     public array getStaticProperties()
  34931.     public array getDefaultProperties()
  34932.     public bool isIterateable()
  34933.     public bool implementsInterface(string name)
  34934.     public ReflectionExtension getExtension()
  34935.     public string getExtensionName()
  34936. }
  34937. ?></PRE
  34938. ></TD
  34939. ></TR
  34940. ></TABLE
  34941. ><P
  34942. ></P
  34943. ></DIV
  34944. ><DIV
  34945. CLASS="note"
  34946. ><BLOCKQUOTE
  34947. CLASS="note"
  34948. ><P
  34949. ><B
  34950. >Note: </B
  34951. >
  34952.      <B
  34953. CLASS="function"
  34954. >hasMethod()</B
  34955. > was added in PHP 5.1.0.
  34956.     </P
  34957. ></BLOCKQUOTE
  34958. ></DIV
  34959. ><P
  34960. >     To introspect a class, you will first have to create an instance
  34961.     of the <B
  34962. CLASS="classname"
  34963. >ReflectionClass</B
  34964. > class. You can then
  34965.     call any of the above methods on this instance.
  34966.    </P
  34967. ><TABLE
  34968. WIDTH="100%"
  34969. BORDER="0"
  34970. CELLPADDING="0"
  34971. CELLSPACING="0"
  34972. CLASS="EXAMPLE"
  34973. ><TR
  34974. ><TD
  34975. ><DIV
  34976. CLASS="example"
  34977. ><A
  34978. NAME="AEN5803"
  34979. ></A
  34980. ><P
  34981. ><B
  34982. >Example 19-34. Using the <B
  34983. CLASS="classname"
  34984. >ReflectionClass</B
  34985. > class</B
  34986. ></P
  34987. ><TABLE
  34988. BORDER="0"
  34989. BGCOLOR="#E0E0E0"
  34990. CELLPADDING="5"
  34991. ><TR
  34992. ><TD
  34993. ><PRE
  34994. CLASS="php"
  34995. ><?php
  34996. interface Serializable
  34997. {
  34998.     // ...
  34999. }
  35000.  
  35001. class Object
  35002. {
  35003.     // ...
  35004. }
  35005.  
  35006. /**
  35007.  * A counter class
  35008.  */
  35009. class Counter extends Object implements Serializable 
  35010. {
  35011.     const START = 0;
  35012.     private static $c = Counter::START;
  35013.  
  35014.     /**
  35015.      * Invoke counter
  35016.      *
  35017.      * @access  public
  35018.      * @return  int
  35019.      */
  35020.     public function count() {
  35021.         return self::$c++;
  35022.     }
  35023. }
  35024.  
  35025. // Create an instance of the ReflectionClass class
  35026. $class = new ReflectionClass('Counter');
  35027.  
  35028. // Print out basic information
  35029. printf(
  35030.     "===> The %s%s%s %s '%s' [extends %s]\n" .
  35031.     "     declared in %s\n" .
  35032.     "     lines %d to %d\n" .
  35033.     "     having the modifiers %d [%s]\n",
  35034.         $class->isInternal() ? 'internal' : 'user-defined',
  35035.         $class->isAbstract() ? ' abstract' : '',
  35036.         $class->isFinal() ? ' final' : '',
  35037.         $class->isInterface() ? 'interface' : 'class',
  35038.         $class->getName(),
  35039.         var_export($class->getParentClass(), 1),
  35040.         $class->getFileName(),
  35041.         $class->getStartLine(),
  35042.         $class->getEndline(),
  35043.         $class->getModifiers(),
  35044.         implode(' ', Reflection::getModifierNames($class->getModifiers()))
  35045. );
  35046.  
  35047. // Print documentation comment
  35048. printf("---> Documentation:\n %s\n", var_export($class->getDocComment(), 1));
  35049.  
  35050. // Print which interfaces are implemented by this class
  35051. printf("---> Implements:\n %s\n", var_export($class->getInterfaces(), 1));
  35052.  
  35053. // Print class constants
  35054. printf("---> Constants: %s\n", var_export($class->getConstants(), 1));
  35055.  
  35056. // Print class properties
  35057. printf("---> Properties: %s\n", var_export($class->getProperties(), 1));
  35058.  
  35059. // Print class methods
  35060. printf("---> Methods: %s\n", var_export($class->getMethods(), 1));
  35061.  
  35062. // If this class is instantiable, create an instance
  35063. if ($class->isInstantiable()) {
  35064.     $counter = $class->newInstance();
  35065.  
  35066.     echo '---> $counter is instance? '; 
  35067.     echo $class->isInstance($counter) ? 'yes' : 'no';
  35068.  
  35069.     echo "\n---> new Object() is instance? ";
  35070.     echo $class->isInstance(new Object()) ? 'yes' : 'no';
  35071. }
  35072. ?></PRE
  35073. ></TD
  35074. ></TR
  35075. ></TABLE
  35076. ></DIV
  35077. ></TD
  35078. ></TR
  35079. ></TABLE
  35080. ><DIV
  35081. CLASS="note"
  35082. ><BLOCKQUOTE
  35083. CLASS="note"
  35084. ><P
  35085. ><B
  35086. >Note: </B
  35087. >
  35088.      The method <B
  35089. CLASS="function"
  35090. >newInstance()</B
  35091. > accepts a variable number of
  35092.      arguments which are passed to the function just as in
  35093.      <A
  35094. HREF="#function.call-user-func"
  35095. ><B
  35096. CLASS="function"
  35097. >call_user_func()</B
  35098. ></A
  35099. >.
  35100.     </P
  35101. ></BLOCKQUOTE
  35102. ></DIV
  35103. ><DIV
  35104. CLASS="note"
  35105. ><BLOCKQUOTE
  35106. CLASS="note"
  35107. ><P
  35108. ><B
  35109. >Note: </B
  35110. >
  35111.      <VAR
  35112. CLASS="literal"
  35113. >$class = new ReflectionClass('Foo'); $class->isInstance($arg)</VAR
  35114. >
  35115.      is equivalent to <VAR
  35116. CLASS="literal"
  35117. >$arg instanceof Foo</VAR
  35118. > or 
  35119.      <VAR
  35120. CLASS="literal"
  35121. >is_a($arg, 'Foo')</VAR
  35122. >.
  35123.     </P
  35124. ></BLOCKQUOTE
  35125. ></DIV
  35126. ></DIV
  35127. ><DIV
  35128. CLASS="sect2"
  35129. ><HR><H3
  35130. CLASS="sect2"
  35131. ><A
  35132. NAME="language.oop5.reflection.reflectionmethod"
  35133. ><B
  35134. CLASS="classname"
  35135. >ReflectionMethod</B
  35136. ></A
  35137. ></H3
  35138. ><P
  35139. >     The <B
  35140. CLASS="classname"
  35141. >ReflectionMethod</B
  35142. > class lets you
  35143.     reverse-engineer class methods.
  35144.    </P
  35145. ><DIV
  35146. CLASS="informalexample"
  35147. ><P
  35148. ></P
  35149. ><A
  35150. NAME="AEN5821"
  35151. ></A
  35152. ><TABLE
  35153. BORDER="0"
  35154. BGCOLOR="#E0E0E0"
  35155. CELLPADDING="5"
  35156. ><TR
  35157. ><TD
  35158. ><PRE
  35159. CLASS="php"
  35160. ><?php
  35161. class ReflectionMethod extends ReflectionFunction
  35162. {
  35163.     public __construct(mixed class, string name)
  35164.     public string __toString()
  35165.     public static string export()
  35166.     public mixed invoke(stdclass object, mixed* args)
  35167.     public moxed invokeArgs(stdclass object, array args)
  35168.     public bool isFinal()
  35169.     public bool isAbstract()
  35170.     public bool isPublic()
  35171.     public bool isPrivate()
  35172.     public bool isProtected()
  35173.     public bool isStatic()
  35174.     public bool isConstructor()
  35175.     public bool isDestructor()
  35176.     public int getModifiers()
  35177.     public ReflectionClass getDeclaringClass()
  35178.  
  35179.     // Inherited from ReflectionFunction
  35180.     final private __clone()
  35181.     public string getName()
  35182.     public bool isInternal()
  35183.     public bool isUserDefined()
  35184.     public string getFileName()
  35185.     public int getStartLine()
  35186.     public int getEndLine()
  35187.     public string getDocComment()
  35188.     public array getStaticVariables()
  35189.     public bool returnsReference()
  35190.     public ReflectionParameter[] getParameters()
  35191.     public int getNumberOfParameters()
  35192.     public int getNumberOfRequiredParameters()
  35193. }
  35194. ?></PRE
  35195. ></TD
  35196. ></TR
  35197. ></TABLE
  35198. ><P
  35199. ></P
  35200. ></DIV
  35201. ><P
  35202. >     To introspect a method, you will first have to create an instance
  35203.     of the <B
  35204. CLASS="classname"
  35205. >ReflectionMethod</B
  35206. > class. You can then call
  35207.     any of the above methods on this instance.
  35208.    </P
  35209. ><TABLE
  35210. WIDTH="100%"
  35211. BORDER="0"
  35212. CELLPADDING="0"
  35213. CELLSPACING="0"
  35214. CLASS="EXAMPLE"
  35215. ><TR
  35216. ><TD
  35217. ><DIV
  35218. CLASS="example"
  35219. ><A
  35220. NAME="AEN5825"
  35221. ></A
  35222. ><P
  35223. ><B
  35224. >Example 19-35. Using the <B
  35225. CLASS="classname"
  35226. >ReflectionMethod</B
  35227. > class</B
  35228. ></P
  35229. ><TABLE
  35230. BORDER="0"
  35231. BGCOLOR="#E0E0E0"
  35232. CELLPADDING="5"
  35233. ><TR
  35234. ><TD
  35235. ><PRE
  35236. CLASS="php"
  35237. ><?php
  35238. class Counter
  35239. {
  35240.     private static $c = 0;
  35241.  
  35242.     /**
  35243.      * Increment counter
  35244.      *
  35245.      * @final
  35246.      * @static
  35247.      * @access  public
  35248.      * @return  int
  35249.      */
  35250.     final public static function increment()
  35251.     {
  35252.         return ++self::$c;
  35253.     }
  35254. }
  35255.  
  35256. // Create an instance of the Reflection_Method class
  35257. $method = new ReflectionMethod('Counter', 'increment');
  35258.  
  35259. // Print out basic information
  35260. printf(
  35261.     "===> The %s%s%s%s%s%s%s method '%s' (which is %s)\n" .
  35262.     "     declared in %s\n" .
  35263.     "     lines %d to %d\n" .
  35264.     "     having the modifiers %d[%s]\n",
  35265.         $method->isInternal() ? 'internal' : 'user-defined',
  35266.         $method->isAbstract() ? ' abstract' : '',
  35267.         $method->isFinal() ? ' final' : '',
  35268.         $method->isPublic() ? ' public' : '',
  35269.         $method->isPrivate() ? ' private' : '',
  35270.         $method->isProtected() ? ' protected' : '',
  35271.         $method->isStatic() ? ' static' : '',
  35272.         $method->getName(),
  35273.         $method->isConstructor() ? 'the constructor' : 'a regular method',
  35274.         $method->getFileName(),
  35275.         $method->getStartLine(),
  35276.         $method->getEndline(),
  35277.         $method->getModifiers(),
  35278.         implode(' ', Reflection::getModifierNames($method->getModifiers()))
  35279. );
  35280.  
  35281. // Print documentation comment
  35282. printf("---> Documentation:\n %s\n", var_export($method->getDocComment(), 1));
  35283.  
  35284. // Print static variables if existant
  35285. if ($statics= $method->getStaticVariables()) {
  35286.     printf("---> Static variables: %s\n", var_export($statics, 1));
  35287. }
  35288.  
  35289. // Invoke the method
  35290. printf("---> Invokation results in: ");
  35291. var_dump($method->invoke(NULL));
  35292. ?></PRE
  35293. ></TD
  35294. ></TR
  35295. ></TABLE
  35296. ></DIV
  35297. ></TD
  35298. ></TR
  35299. ></TABLE
  35300. ><DIV
  35301. CLASS="note"
  35302. ><BLOCKQUOTE
  35303. CLASS="note"
  35304. ><P
  35305. ><B
  35306. >Note: </B
  35307. >
  35308.      Trying to invoke private, protected or abstract methods will result
  35309.      in an exception being thrown from the <B
  35310. CLASS="function"
  35311. >invoke()</B
  35312. >
  35313.      method.
  35314.     </P
  35315. ></BLOCKQUOTE
  35316. ></DIV
  35317. ><DIV
  35318. CLASS="note"
  35319. ><BLOCKQUOTE
  35320. CLASS="note"
  35321. ><P
  35322. ><B
  35323. >Note: </B
  35324. >
  35325.      For static methods as seen above, you should pass NULL as the first
  35326.      argument to <B
  35327. CLASS="function"
  35328. >invoke()</B
  35329. >. For non-static methods, pass 
  35330.      an instance of the class.
  35331.     </P
  35332. ></BLOCKQUOTE
  35333. ></DIV
  35334. ></DIV
  35335. ><DIV
  35336. CLASS="sect2"
  35337. ><HR><H3
  35338. CLASS="sect2"
  35339. ><A
  35340. NAME="language.oop5.reflection.reflectionproperty"
  35341. ><B
  35342. CLASS="classname"
  35343. >ReflectionProperty</B
  35344. ></A
  35345. ></H3
  35346. ><P
  35347. >     The <B
  35348. CLASS="classname"
  35349. >ReflectionProperty</B
  35350. > class lets you
  35351.     reverse-engineer class properties.
  35352.    </P
  35353. ><DIV
  35354. CLASS="informalexample"
  35355. ><P
  35356. ></P
  35357. ><A
  35358. NAME="AEN5840"
  35359. ></A
  35360. ><TABLE
  35361. BORDER="0"
  35362. BGCOLOR="#E0E0E0"
  35363. CELLPADDING="5"
  35364. ><TR
  35365. ><TD
  35366. ><PRE
  35367. CLASS="php"
  35368. ><?php
  35369. class ReflectionProperty implements Reflector
  35370. {
  35371.     final private __clone()
  35372.     public __construct(mixed class, string name)
  35373.     public string __toString()
  35374.     public static string export()
  35375.     public string getName()
  35376.     public bool isPublic()
  35377.     public bool isPrivate()
  35378.     public bool isProtected()
  35379.     public bool isStatic()
  35380.     public bool isDefault()
  35381.     public int getModifiers()
  35382.     public mixed getValue(stdclass object)
  35383.     public void setValue(stdclass object, mixed value)
  35384.     public ReflectionClass getDeclaringClass()
  35385. }
  35386. ?></PRE
  35387. ></TD
  35388. ></TR
  35389. ></TABLE
  35390. ><P
  35391. ></P
  35392. ></DIV
  35393. ><P
  35394. >     To introspect a property, you will first have to create an instance
  35395.     of the <B
  35396. CLASS="classname"
  35397. >ReflectionProperty</B
  35398. > class. You can then
  35399.     call any of the above methods on this instance.
  35400.    </P
  35401. ><TABLE
  35402. WIDTH="100%"
  35403. BORDER="0"
  35404. CELLPADDING="0"
  35405. CELLSPACING="0"
  35406. CLASS="EXAMPLE"
  35407. ><TR
  35408. ><TD
  35409. ><DIV
  35410. CLASS="example"
  35411. ><A
  35412. NAME="AEN5844"
  35413. ></A
  35414. ><P
  35415. ><B
  35416. >Example 19-36. Using the <B
  35417. CLASS="classname"
  35418. >ReflectionProperty</B
  35419. > class</B
  35420. ></P
  35421. ><TABLE
  35422. BORDER="0"
  35423. BGCOLOR="#E0E0E0"
  35424. CELLPADDING="5"
  35425. ><TR
  35426. ><TD
  35427. ><PRE
  35428. CLASS="php"
  35429. ><?php
  35430. class String
  35431. {
  35432.     public $length  = 5;
  35433. }
  35434.  
  35435. // Create an instance of the ReflectionProperty class
  35436. $prop = new ReflectionProperty('String', 'length');
  35437.  
  35438. // Print out basic information
  35439. printf(
  35440.     "===> The%s%s%s%s property '%s' (which was %s)\n" .
  35441.     "     having the modifiers %s\n",
  35442.         $prop->isPublic() ? ' public' : '',
  35443.         $prop->isPrivate() ? ' private' : '',
  35444.         $prop->isProtected() ? ' protected' : '',
  35445.         $prop->isStatic() ? ' static' : '',
  35446.         $prop->getName(),
  35447.         $prop->isDefault() ? 'declared at compile-time' : 'created at run-time',
  35448.         var_export(Reflection::getModifierNames($prop->getModifiers()), 1)
  35449. );
  35450.  
  35451. // Create an instance of String
  35452. $obj= new String();
  35453.  
  35454. // Get current value
  35455. printf("---> Value is: ");
  35456. var_dump($prop->getValue($obj));
  35457.  
  35458. // Change value
  35459. $prop->setValue($obj, 10);
  35460. printf("---> Setting value to 10, new value is: ");
  35461. var_dump($prop->getValue($obj));
  35462.  
  35463. // Dump object
  35464. var_dump($obj);
  35465. ?></PRE
  35466. ></TD
  35467. ></TR
  35468. ></TABLE
  35469. ></DIV
  35470. ></TD
  35471. ></TR
  35472. ></TABLE
  35473. ><DIV
  35474. CLASS="note"
  35475. ><BLOCKQUOTE
  35476. CLASS="note"
  35477. ><P
  35478. ><B
  35479. >Note: </B
  35480. >
  35481.      Trying to get or set private or protected class property's values
  35482.      will result in an exception being thrown.
  35483.     </P
  35484. ></BLOCKQUOTE
  35485. ></DIV
  35486. ></DIV
  35487. ><DIV
  35488. CLASS="sect2"
  35489. ><HR><H3
  35490. CLASS="sect2"
  35491. ><A
  35492. NAME="language.oop5.reflection.reflectionextension"
  35493. ><B
  35494. CLASS="classname"
  35495. >ReflectionExtension</B
  35496. ></A
  35497. ></H3
  35498. ><P
  35499. >     The <B
  35500. CLASS="classname"
  35501. >ReflectionExtension</B
  35502. > class lets you
  35503.     reverse-engineer extensions. You can retrieve all loaded extensions
  35504.     at runtime using the <A
  35505. HREF="#function.get-loaded-extensions"
  35506. ><B
  35507. CLASS="function"
  35508. >get_loaded_extensions()</B
  35509. ></A
  35510. >.
  35511.    </P
  35512. ><DIV
  35513. CLASS="informalexample"
  35514. ><P
  35515. ></P
  35516. ><A
  35517. NAME="AEN5856"
  35518. ></A
  35519. ><TABLE
  35520. BORDER="0"
  35521. BGCOLOR="#E0E0E0"
  35522. CELLPADDING="5"
  35523. ><TR
  35524. ><TD
  35525. ><PRE
  35526. CLASS="php"
  35527. ><?php
  35528. class ReflectionExtension implements Reflector {
  35529.     final private __clone()
  35530.     public __construct(string name)
  35531.     public string __toString()
  35532.     public static string export()
  35533.     public string getName()
  35534.     public string getVersion()
  35535.     public ReflectionFunction[] getFunctions()
  35536.     public array getConstants()
  35537.     public array getINIEntries()
  35538.     public ReflectionClass[] getClasses()
  35539.     public array getClassNames()
  35540. }
  35541. ?></PRE
  35542. ></TD
  35543. ></TR
  35544. ></TABLE
  35545. ><P
  35546. ></P
  35547. ></DIV
  35548. ><P
  35549. >     To introspect an extension, you will first have to create an instance
  35550.     of the <B
  35551. CLASS="classname"
  35552. >ReflectionExtension</B
  35553. > class. You can then call
  35554.     any of the above methods on this instance.
  35555.    </P
  35556. ><TABLE
  35557. WIDTH="100%"
  35558. BORDER="0"
  35559. CELLPADDING="0"
  35560. CELLSPACING="0"
  35561. CLASS="EXAMPLE"
  35562. ><TR
  35563. ><TD
  35564. ><DIV
  35565. CLASS="example"
  35566. ><A
  35567. NAME="AEN5860"
  35568. ></A
  35569. ><P
  35570. ><B
  35571. >Example 19-37. Using the <B
  35572. CLASS="classname"
  35573. >ReflectionExtension</B
  35574. > class</B
  35575. ></P
  35576. ><TABLE
  35577. BORDER="0"
  35578. BGCOLOR="#E0E0E0"
  35579. CELLPADDING="5"
  35580. ><TR
  35581. ><TD
  35582. ><PRE
  35583. CLASS="php"
  35584. ><?php
  35585. // Create an instance of the ReflectionProperty class
  35586. $ext = new ReflectionExtension('standard');
  35587.  
  35588. // Print out basic information
  35589. printf(
  35590.     "Name        : %s\n" .
  35591.     "Version     : %s\n" .
  35592.     "Functions   : [%d] %s\n" .
  35593.     "Constants   : [%d] %s\n" .
  35594.     "INI entries : [%d] %s\n" .
  35595.     "Classes     : [%d] %s\n",
  35596.         $ext->getName(),
  35597.         $ext->getVersion() ? $ext->getVersion() : 'NO_VERSION',
  35598.         sizeof($ext->getFunctions()),
  35599.         var_export($ext->getFunctions(), 1),
  35600.  
  35601.         sizeof($ext->getConstants()),
  35602.         var_export($ext->getConstants(), 1),
  35603.  
  35604.         sizeof($ext->getINIEntries()),
  35605.         var_export($ext->getINIEntries(), 1),
  35606.  
  35607.         sizeof($ext->getClassNames()),
  35608.         var_export($ext->getClassNames(), 1)
  35609. );
  35610. ?></PRE
  35611. ></TD
  35612. ></TR
  35613. ></TABLE
  35614. ></DIV
  35615. ></TD
  35616. ></TR
  35617. ></TABLE
  35618. ></DIV
  35619. ><DIV
  35620. CLASS="sect2"
  35621. ><HR><H3
  35622. CLASS="sect2"
  35623. ><A
  35624. NAME="language.oop5.reflection.extending"
  35625. >Extending the reflection classes</A
  35626. ></H3
  35627. ><P
  35628. >     In case you want to create specialized versions of the built-in
  35629.     classes (say, for creating colorized HTML when being exported,
  35630.     having easy-access member variables instead of methods or
  35631.     having utility methods), you may go ahead and extend them.
  35632.    </P
  35633. ><TABLE
  35634. WIDTH="100%"
  35635. BORDER="0"
  35636. CELLPADDING="0"
  35637. CELLSPACING="0"
  35638. CLASS="EXAMPLE"
  35639. ><TR
  35640. ><TD
  35641. ><DIV
  35642. CLASS="example"
  35643. ><A
  35644. NAME="AEN5867"
  35645. ></A
  35646. ><P
  35647. ><B
  35648. >Example 19-38. Extending the built-in classes</B
  35649. ></P
  35650. ><TABLE
  35651. BORDER="0"
  35652. BGCOLOR="#E0E0E0"
  35653. CELLPADDING="5"
  35654. ><TR
  35655. ><TD
  35656. ><PRE
  35657. CLASS="php"
  35658. ><?php
  35659. /**
  35660.  * My Reflection_Method class
  35661.  */
  35662. class My_Reflection_Method extends ReflectionMethod
  35663. {
  35664.     public $visibility = '';
  35665.  
  35666.     public function __construct($o, $m)
  35667.     {
  35668.         parent::__construct($o, $m);
  35669.         $this->visibility= Reflection::getModifierNames($this->getModifiers());
  35670.     }
  35671. }
  35672.  
  35673. /**
  35674.  * Demo class #1
  35675.  *
  35676.  */
  35677. class T {
  35678.     protected function x() {}
  35679. }
  35680.  
  35681. /**
  35682.  * Demo class #2
  35683.  *
  35684.  */
  35685. class U extends T {
  35686.     function x() {}
  35687. }
  35688.  
  35689. // Print out information
  35690. var_dump(new My_Reflection_Method('U', 'x'));
  35691. ?></PRE
  35692. ></TD
  35693. ></TR
  35694. ></TABLE
  35695. ></DIV
  35696. ></TD
  35697. ></TR
  35698. ></TABLE
  35699. ><DIV
  35700. CLASS="note"
  35701. ><BLOCKQUOTE
  35702. CLASS="note"
  35703. ><P
  35704. ><B
  35705. >Note: </B
  35706. >
  35707.      Caution: If you're overwriting the constructor, remember to call
  35708.      the parent's constructor _before_ any code you insert. Failing to
  35709.      do so will result in the following:
  35710.      <VAR
  35711. CLASS="literal"
  35712. >       Fatal error: Internal error: Failed to retrieve the reflection object
  35713.      </VAR
  35714. >
  35715.     </P
  35716. ></BLOCKQUOTE
  35717. ></DIV
  35718. ></DIV
  35719. ></DIV
  35720. ><DIV
  35721. CLASS="sect1"
  35722. ><HR><H2
  35723. CLASS="sect1"
  35724. ><A
  35725. NAME="language.oop5.typehinting"
  35726. >Type Hinting</A
  35727. ></H2
  35728. ><P
  35729. >    PHP 5 introduces Type Hinting. Functions are now able to force parameters
  35730.    to be objects by specifying the name of the class in the function prototype.
  35731.   </P
  35732. ><TABLE
  35733. WIDTH="100%"
  35734. BORDER="0"
  35735. CELLPADDING="0"
  35736. CELLSPACING="0"
  35737. CLASS="EXAMPLE"
  35738. ><TR
  35739. ><TD
  35740. ><DIV
  35741. CLASS="example"
  35742. ><A
  35743. NAME="AEN5876"
  35744. ></A
  35745. ><P
  35746. ><B
  35747. >Example 19-39. Type Hinting example</B
  35748. ></P
  35749. ><TABLE
  35750. BORDER="0"
  35751. BGCOLOR="#E0E0E0"
  35752. CELLPADDING="5"
  35753. ><TR
  35754. ><TD
  35755. ><PRE
  35756. CLASS="php"
  35757. ><?php
  35758. // An example class
  35759. class MyClass
  35760. {
  35761.     /**
  35762.      * A test function
  35763.      *
  35764.      * First parameter must be an object of type OtherClass
  35765.      */
  35766.     public function test(OtherClass $otherclass) {
  35767.         echo $otherclass->var;
  35768.     }
  35769. }
  35770.  
  35771. // Another example class
  35772. class OtherClass {
  35773.     public $var = 'Hello World';
  35774. }
  35775. ?></PRE
  35776. ></TD
  35777. ></TR
  35778. ></TABLE
  35779. ><P
  35780. >     Failing to satisfy the type hint results in a fatal error.
  35781.    </P
  35782. ><TABLE
  35783. BORDER="0"
  35784. BGCOLOR="#E0E0E0"
  35785. CELLPADDING="5"
  35786. ><TR
  35787. ><TD
  35788. ><PRE
  35789. CLASS="php"
  35790. ><?php
  35791. // An instance of each class
  35792. $myclass = new MyClass;
  35793. $otherclass = new OtherClass;
  35794.  
  35795. // Fatal Error: Argument 1 must be an object of class OtherClass
  35796. $myclass->test('hello');
  35797.  
  35798. // Fatal Error: Argument 1 must be an instance of OtherClass
  35799. $foo = new stdClass;
  35800. $myclass->test($foo);
  35801.  
  35802. // Fatal Error: Argument 1 must not be null
  35803. $myclass->test(null);
  35804.  
  35805. // Works: Prints Hello World
  35806. $myclass->test($otherclass);
  35807. ?></PRE
  35808. ></TD
  35809. ></TR
  35810. ></TABLE
  35811. ><P
  35812. >     Type hinting also works with functions:
  35813.    </P
  35814. ><TABLE
  35815. BORDER="0"
  35816. BGCOLOR="#E0E0E0"
  35817. CELLPADDING="5"
  35818. ><TR
  35819. ><TD
  35820. ><PRE
  35821. CLASS="php"
  35822. ><?php
  35823. // An example class
  35824. class MyClass {
  35825.     public $var = 'Hello World';
  35826. }
  35827.  
  35828. /**
  35829.  * A test function
  35830.  *
  35831.  * First parameter must be an object of type MyClass
  35832.  */
  35833. function MyFunction (MyClass $foo) {
  35834.     echo $foo->var;
  35835. }
  35836.  
  35837. // Works
  35838. $myclass = new MyClass;
  35839. MyFunction($myclass);
  35840. ?></PRE
  35841. ></TD
  35842. ></TR
  35843. ></TABLE
  35844. ></DIV
  35845. ></TD
  35846. ></TR
  35847. ></TABLE
  35848. ><P
  35849. >    Type Hints can only be of the <A
  35850. HREF="#language.types.object"
  35851. ><B
  35852. CLASS="type"
  35853. >object</B
  35854. ></A
  35855. > type. Traditional
  35856.    type hinting with <A
  35857. HREF="#language.types.integer"
  35858. ><B
  35859. CLASS="type"
  35860. >int</B
  35861. ></A
  35862. > and <A
  35863. HREF="#language.types.string"
  35864. ><B
  35865. CLASS="type"
  35866. >string</B
  35867. ></A
  35868. > are not
  35869.    supported.
  35870.   </P
  35871. ></DIV
  35872. ></DIV
  35873. ><DIV
  35874. CLASS="chapter"
  35875. ><HR><H1
  35876. ><A
  35877. NAME="language.exceptions"
  35878. >Chapter 20. Exceptions</A
  35879. ></H1
  35880. ><P
  35881. >    PHP 5 has an exception model similar to that of other programming languages.
  35882.    An exception can be thrown, try and caught within PHP. A Try block must
  35883.    include at least one catch block. Multiple catch blocks can be used to
  35884.    catch different classtypes; execution will continue after that last catch
  35885.    block defined in sequence. Exceptions can be thrown within catch blocks.
  35886.   </P
  35887. ><P
  35888. >    When an exception is thrown, code following the statement will not be
  35889.    executed and PHP will attempt to find the first matching catch block. If an
  35890.    exception is not caught a PHP Fatal Error will be issued with an Uncaught
  35891.    Exception message, unless there has been a handler defined with
  35892.    <A
  35893. HREF="#function.set-exception-handler"
  35894. ><B
  35895. CLASS="function"
  35896. >set_exception_handler()</B
  35897. ></A
  35898. >.
  35899.   </P
  35900. ><TABLE
  35901. WIDTH="100%"
  35902. BORDER="0"
  35903. CELLPADDING="0"
  35904. CELLSPACING="0"
  35905. CLASS="EXAMPLE"
  35906. ><TR
  35907. ><TD
  35908. ><DIV
  35909. CLASS="example"
  35910. ><A
  35911. NAME="AEN5892"
  35912. ></A
  35913. ><P
  35914. ><B
  35915. >Example 20-1. Throwing an Exception</B
  35916. ></P
  35917. ><TABLE
  35918. BORDER="0"
  35919. BGCOLOR="#E0E0E0"
  35920. CELLPADDING="5"
  35921. ><TR
  35922. ><TD
  35923. ><PRE
  35924. CLASS="php"
  35925. ><?php
  35926. try {
  35927.     $error = 'Always throw this error';
  35928.     throw new Exception($error);
  35929.  
  35930.     // Code following an exception is not executed.
  35931.     echo 'Never executed';
  35932.  
  35933. } catch (Exception $e) {
  35934.     echo 'Caught exception: ',  $e->getMessage(), "\n";
  35935. }
  35936.  
  35937. // Continue execution
  35938. echo 'Hello World';
  35939. ?></PRE
  35940. ></TD
  35941. ></TR
  35942. ></TABLE
  35943. ></DIV
  35944. ></TD
  35945. ></TR
  35946. ></TABLE
  35947. ><DIV
  35948. CLASS="sect1"
  35949. ><HR><H2
  35950. CLASS="sect1"
  35951. ><A
  35952. NAME="language.exceptions.extending"
  35953. >Extending Exceptions</A
  35954. ></H2
  35955. ><P
  35956. >     A User defined Exception class can be defined by extending the built-in
  35957.     Exception class. The members and properties below, show what is accessible
  35958.     within the child class that derives from the built-in Exception class.
  35959.    </P
  35960. ><TABLE
  35961. WIDTH="100%"
  35962. BORDER="0"
  35963. CELLPADDING="0"
  35964. CELLSPACING="0"
  35965. CLASS="EXAMPLE"
  35966. ><TR
  35967. ><TD
  35968. ><DIV
  35969. CLASS="example"
  35970. ><A
  35971. NAME="AEN5898"
  35972. ></A
  35973. ><P
  35974. ><B
  35975. >Example 20-2. The Built in Exception class</B
  35976. ></P
  35977. ><TABLE
  35978. BORDER="0"
  35979. BGCOLOR="#E0E0E0"
  35980. CELLPADDING="5"
  35981. ><TR
  35982. ><TD
  35983. ><PRE
  35984. CLASS="php"
  35985. ><?php
  35986. class Exception
  35987. {
  35988.     protected $message = 'Unknown exception';   // exception message
  35989.     protected $code = 0;                        // user defined exception code
  35990.     protected $file;                            // source filename of exception
  35991.     protected $line;                            // source line of exception
  35992.  
  35993.     function __construct($message = null, $code = 0);
  35994.  
  35995.     final function getMessage();                // message of exception 
  35996.     final function getCode();                   // code of exception
  35997.     final function getFile();                   // source filename
  35998.     final function getLine();                   // source line
  35999.     final function getTrace();                  // an array of the backtrace()
  36000.     final function getTraceAsString();          // formated string of trace
  36001.  
  36002.     /* Overrideable */
  36003.     function __toString();                       // formated string for display
  36004. }
  36005. ?></PRE
  36006. ></TD
  36007. ></TR
  36008. ></TABLE
  36009. ></DIV
  36010. ></TD
  36011. ></TR
  36012. ></TABLE
  36013. ><P
  36014. >     If a class extends the built-in Exception class and re-defines the <A
  36015. HREF="#language.oop5.decon"
  36016. >constructor</A
  36017. >, it is highly recomended
  36018.     that it also call <A
  36019. HREF="#language.oop5.paamayim-nekudotayim"
  36020. >parent::__construct()</A
  36021. > 
  36022.     to ensure all available data has been properly assigned. The <A
  36023. HREF="#language.oop5.magic"
  36024. >__toString()</A
  36025. > method can be overriden
  36026.     to provide a custom output when the object is presented as a string.
  36027.    </P
  36028. ><TABLE
  36029. WIDTH="100%"
  36030. BORDER="0"
  36031. CELLPADDING="0"
  36032. CELLSPACING="0"
  36033. CLASS="EXAMPLE"
  36034. ><TR
  36035. ><TD
  36036. ><DIV
  36037. CLASS="example"
  36038. ><A
  36039. NAME="AEN5905"
  36040. ></A
  36041. ><P
  36042. ><B
  36043. >Example 20-3. Extending the Exception class</B
  36044. ></P
  36045. ><TABLE
  36046. BORDER="0"
  36047. BGCOLOR="#E0E0E0"
  36048. CELLPADDING="5"
  36049. ><TR
  36050. ><TD
  36051. ><PRE
  36052. CLASS="php"
  36053. ><?php
  36054. /**
  36055.  * Define a custom exception class
  36056.  */
  36057. class MyException extends Exception
  36058. {
  36059.     // Redefine the exception so message isn't optional
  36060.     public function __construct($message, $code = 0) {
  36061.         // some code
  36062.     
  36063.         // make sure everything is assigned properly
  36064.         parent::__construct($message, $code);
  36065.     }
  36066.  
  36067.     // custom string representation of object */
  36068.     public function __toString() {
  36069.         return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
  36070.     }
  36071.  
  36072.     public function customFunction() {
  36073.         echo "A Custom function for this type of exception\n";
  36074.     }
  36075. }
  36076.  
  36077.  
  36078. /**
  36079.  * Create a class to test the exception
  36080.  */
  36081. class TestException
  36082. {
  36083.     public $var;
  36084.  
  36085.     const THROW_NONE    = 0;
  36086.     const THROW_CUSTOM  = 1;
  36087.     const THROW_DEFAULT = 2;
  36088.  
  36089.     function __construct($avalue = self::THROW_NONE) {
  36090.  
  36091.         switch ($avalue) {
  36092.             case self::THROW_CUSTOM:
  36093.                 // throw custom exception
  36094.                 throw new MyException('1 is an invalid parameter', 5);
  36095.                 break;
  36096.  
  36097.             case self::THROW_DEFAULT:
  36098.                 // throw default one.
  36099.                 throw new Exception('2 isnt allowed as a parameter', 6);
  36100.                 break;
  36101.  
  36102.             default: 
  36103.                 // No exception, object will be created.
  36104.                 $this->var = $avalue;
  36105.                 break;
  36106.         }
  36107.     }
  36108. }
  36109.  
  36110.  
  36111. // Example 1
  36112. try {
  36113.     $o = new TestException(TestException::THROW_CUSTOM);
  36114. } catch (MyException $e) {      // Will be caught
  36115.     echo "Caught my exception\n", $e;
  36116.     $e->customFunction();
  36117. } catch (Exception $e) {        // Skipped
  36118.     echo "Caught Default Exception\n", $e;
  36119. }
  36120.  
  36121. // Continue execution
  36122. var_dump($o);
  36123. echo "\n\n";
  36124.  
  36125.  
  36126. // Example 2
  36127. try {
  36128.     $o = new TestException(TestException::THROW_DEFAULT);
  36129. } catch (MyException $e) {      // Doesn't match this type
  36130.     echo "Caught my exception\n", $e;
  36131.     $e->customFunction();
  36132. } catch (Exception $e) {        // Will be caught
  36133.     echo "Caught Default Exception\n", $e;
  36134. }
  36135.  
  36136. // Continue execution
  36137. var_dump($o);
  36138. echo "\n\n";
  36139.  
  36140.  
  36141. // Example 3
  36142. try {
  36143.     $o = new TestException(TestException::THROW_CUSTOM);
  36144. } catch (Exception $e) {        // Will be caught
  36145.     echo "Default Exception caught\n", $e;
  36146. }
  36147.  
  36148. // Continue execution
  36149. var_dump($o);
  36150. echo "\n\n";
  36151.  
  36152.  
  36153. // Example 4
  36154. try {
  36155.     $o = new TestException();
  36156. } catch (Exception $e) {        // Skipped, no exception
  36157.     echo "Default Exception caught\n", $e;
  36158. }
  36159.  
  36160. // Continue execution
  36161. var_dump($o);
  36162. echo "\n\n";
  36163. ?></PRE
  36164. ></TD
  36165. ></TR
  36166. ></TABLE
  36167. ></DIV
  36168. ></TD
  36169. ></TR
  36170. ></TABLE
  36171. ></DIV
  36172. ></DIV
  36173. ><DIV
  36174. CLASS="chapter"
  36175. ><HR><H1
  36176. ><A
  36177. NAME="language.references"
  36178. >Chapter 21. References Explained</A
  36179. ></H1
  36180. ><DIV
  36181. CLASS="sect1"
  36182. ><H2
  36183. CLASS="sect1"
  36184. ><A
  36185. NAME="language.references.whatare"
  36186. >What References Are</A
  36187. ></H2
  36188. ><P
  36189. >  
  36190.     References in PHP are a means to access the same variable content 
  36191.     by different names. They are not like C pointers, they are symbol
  36192.     table aliases. Note that in PHP, variable name and variable content 
  36193.     are different, so the same content can have different names.
  36194.     The most close analogy is with Unix filenames and files -
  36195.     variable names are directory entries, while variable contents is
  36196.     the file itself. References can be thought of as hardlinking in
  36197.     Unix filesystem.
  36198.    </P
  36199. ></DIV
  36200. ><DIV
  36201. CLASS="sect1"
  36202. ><HR><H2
  36203. CLASS="sect1"
  36204. ><A
  36205. NAME="language.references.whatdo"
  36206. >What References Do</A
  36207. ></H2
  36208. ><P
  36209. >     PHP references allow you to make two variables to refer to the
  36210.     same content. Meaning, when you do:
  36211.     <DIV
  36212. CLASS="informalexample"
  36213. ><P
  36214. ></P
  36215. ><A
  36216. NAME="AEN5916"
  36217. ></A
  36218. ><TABLE
  36219. BORDER="0"
  36220. BGCOLOR="#E0E0E0"
  36221. CELLPADDING="5"
  36222. ><TR
  36223. ><TD
  36224. ><PRE
  36225. CLASS="php"
  36226. ><?php
  36227. $a =& $b;
  36228. ?></PRE
  36229. ></TD
  36230. ></TR
  36231. ></TABLE
  36232. ><P
  36233. ></P
  36234. ></DIV
  36235. >
  36236.     it means that <VAR
  36237. CLASS="varname"
  36238. >$a</VAR
  36239. > and <VAR
  36240. CLASS="varname"
  36241. >$b</VAR
  36242. >
  36243.     point to the same variable.
  36244.     <DIV
  36245. CLASS="note"
  36246. ><BLOCKQUOTE
  36247. CLASS="note"
  36248. ><P
  36249. ><B
  36250. >Note: </B
  36251. >
  36252.       <VAR
  36253. CLASS="varname"
  36254. >$a</VAR
  36255. > and <VAR
  36256. CLASS="varname"
  36257. >$b</VAR
  36258. > are completely
  36259.       equal here, that's not <VAR
  36260. CLASS="varname"
  36261. >$a</VAR
  36262. > is pointing to
  36263.       <VAR
  36264. CLASS="varname"
  36265. >$b</VAR
  36266. > or vice versa, that's
  36267.       <VAR
  36268. CLASS="varname"
  36269. >$a</VAR
  36270. > and <VAR
  36271. CLASS="varname"
  36272. >$b</VAR
  36273. > pointing to the
  36274.       same place.
  36275.      </P
  36276. ></BLOCKQUOTE
  36277. ></DIV
  36278. >
  36279.    </P
  36280. ><DIV
  36281. CLASS="note"
  36282. ><BLOCKQUOTE
  36283. CLASS="note"
  36284. ><P
  36285. ><B
  36286. >Note: </B
  36287. >
  36288.      If array with references is copied, its values are not dereferenced.
  36289.      This is valid also for arrays passed by value to functions.
  36290.     </P
  36291. ></BLOCKQUOTE
  36292. ></DIV
  36293. ><P
  36294. >    The same syntax can be used with functions, that return references,
  36295.    and with <VAR
  36296. CLASS="literal"
  36297. >new</VAR
  36298. > operator (in PHP 4.0.4 and later):
  36299.     <DIV
  36300. CLASS="informalexample"
  36301. ><P
  36302. ></P
  36303. ><A
  36304. NAME="AEN5932"
  36305. ></A
  36306. ><TABLE
  36307. BORDER="0"
  36308. BGCOLOR="#E0E0E0"
  36309. CELLPADDING="5"
  36310. ><TR
  36311. ><TD
  36312. ><PRE
  36313. CLASS="php"
  36314. ><?php
  36315. $bar =& new fooclass();
  36316. $foo =& find_var($bar);
  36317. ?></PRE
  36318. ></TD
  36319. ></TR
  36320. ></TABLE
  36321. ><P
  36322. ></P
  36323. ></DIV
  36324. >
  36325.     </P
  36326. ><DIV
  36327. CLASS="note"
  36328. ><BLOCKQUOTE
  36329. CLASS="note"
  36330. ><P
  36331. ><B
  36332. >Note: </B
  36333. >
  36334.      Not using the <VAR
  36335. CLASS="literal"
  36336. >&</VAR
  36337. > operator causes a copy of the
  36338.      object to be made. If you use <VAR
  36339. CLASS="literal"
  36340. >$this</VAR
  36341. > in the class it
  36342.      will operate on the current instance of the class. The assignment without
  36343.      <VAR
  36344. CLASS="literal"
  36345. >&</VAR
  36346. > will copy the instance (i.e. the object) and
  36347.      <VAR
  36348. CLASS="literal"
  36349. >$this</VAR
  36350. > will operate on the copy, which is not always
  36351.      what is desired. Usually you want to have a single instance to work with,
  36352.      due to performance and memory consumption issues.
  36353.      </P
  36354. ><P
  36355. >       While you can use the <VAR
  36356. CLASS="literal"
  36357. >@</VAR
  36358. > operator to
  36359.       <SPAN
  36360. CLASS="emphasis"
  36361. ><I
  36362. CLASS="emphasis"
  36363. >mute</I
  36364. ></SPAN
  36365. > any errors in the constructor when using it as
  36366.       <VAR
  36367. CLASS="literal"
  36368. >@new</VAR
  36369. >, this does not work when using the
  36370.       <VAR
  36371. CLASS="literal"
  36372. >&new</VAR
  36373. > statement. This is a limitation of the Zend
  36374.       Engine and will therefore result in a parser error.
  36375.      </P
  36376. ></BLOCKQUOTE
  36377. ></DIV
  36378. ><DIV
  36379. CLASS="warning"
  36380. ><P
  36381. ></P
  36382. ><TABLE
  36383. CLASS="warning"
  36384. BORDER="1"
  36385. WIDTH="100%"
  36386. ><TR
  36387. ><TD
  36388. ALIGN="CENTER"
  36389. ><B
  36390. >Warning</B
  36391. ></TD
  36392. ></TR
  36393. ><TR
  36394. ><TD
  36395. ALIGN="LEFT"
  36396. ><P
  36397. >      If you assign a reference to a variable declared <VAR
  36398. CLASS="literal"
  36399. >global</VAR
  36400. >
  36401.      inside a function, the reference will be visible only inside the function.
  36402.      You can avoid this by using the <VAR
  36403. CLASS="varname"
  36404. >$GLOBALS</VAR
  36405. > array.
  36406.      <TABLE
  36407. WIDTH="100%"
  36408. BORDER="0"
  36409. CELLPADDING="0"
  36410. CELLSPACING="0"
  36411. CLASS="EXAMPLE"
  36412. ><TR
  36413. ><TD
  36414. ><DIV
  36415. CLASS="example"
  36416. ><A
  36417. NAME="AEN5949"
  36418. ></A
  36419. ><P
  36420. ><B
  36421. >Example 21-1. Referencing global variables inside function</B
  36422. ></P
  36423. ><TABLE
  36424. BORDER="0"
  36425. BGCOLOR="#E0E0E0"
  36426. CELLPADDING="5"
  36427. ><TR
  36428. ><TD
  36429. ><PRE
  36430. CLASS="php"
  36431. ><?php
  36432. $var1 = "Example variable";
  36433. $var2 = "";
  36434.  
  36435. function global_references($use_globals)
  36436. {
  36437.     global $var1, $var2;
  36438.     if (!$use_globals) {
  36439.         $var2 =& $var1; // visible only inside the function
  36440.     } else {
  36441.         $GLOBALS["var2"] =& $var1; // visible also in global context
  36442.     }
  36443. }
  36444.  
  36445. global_references(false);
  36446. echo "var2 is set to '$var2'\n"; // var2 is set to ''
  36447. global_references(true);
  36448. echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
  36449. ?></PRE
  36450. ></TD
  36451. ></TR
  36452. ></TABLE
  36453. ></DIV
  36454. ></TD
  36455. ></TR
  36456. ></TABLE
  36457. >
  36458.      Think about <VAR
  36459. CLASS="literal"
  36460. >global $var;</VAR
  36461. > as a shortcut to <VAR
  36462. CLASS="literal"
  36463. >$var
  36464.      =& $GLOBALS['var'];</VAR
  36465. >. Thus assigning other reference
  36466.      to <VAR
  36467. CLASS="literal"
  36468. >$var</VAR
  36469. > only changes the local variable's reference.
  36470.     </P
  36471. ></TD
  36472. ></TR
  36473. ></TABLE
  36474. ></DIV
  36475. ><DIV
  36476. CLASS="note"
  36477. ><BLOCKQUOTE
  36478. CLASS="note"
  36479. ><P
  36480. ><B
  36481. >Note: </B
  36482. >
  36483.      If you assign a value to a variable with references in a <A
  36484. HREF="#control-structures.foreach"
  36485. >foreach</A
  36486. > statement,
  36487.      the references are modified too.
  36488.      <TABLE
  36489. WIDTH="100%"
  36490. BORDER="0"
  36491. CELLPADDING="0"
  36492. CELLSPACING="0"
  36493. CLASS="EXAMPLE"
  36494. ><TR
  36495. ><TD
  36496. ><DIV
  36497. CLASS="example"
  36498. ><A
  36499. NAME="AEN5958"
  36500. ></A
  36501. ><P
  36502. ><B
  36503. >Example 21-2. References and foreach statement</B
  36504. ></P
  36505. ><TABLE
  36506. BORDER="0"
  36507. BGCOLOR="#E0E0E0"
  36508. CELLPADDING="5"
  36509. ><TR
  36510. ><TD
  36511. ><PRE
  36512. CLASS="php"
  36513. ><?php
  36514. $ref = 0;
  36515. $row =& $ref;
  36516. foreach (array(1, 2, 3) as $row) {
  36517.     // do something
  36518. }
  36519. echo $ref; // 3 - last element of the iterated array
  36520. ?></PRE
  36521. ></TD
  36522. ></TR
  36523. ></TABLE
  36524. ></DIV
  36525. ></TD
  36526. ></TR
  36527. ></TABLE
  36528. >
  36529.     </P
  36530. ></BLOCKQUOTE
  36531. ></DIV
  36532. ><DIV
  36533. CLASS="warning"
  36534. ><P
  36535. ></P
  36536. ><TABLE
  36537. CLASS="warning"
  36538. BORDER="1"
  36539. WIDTH="100%"
  36540. ><TR
  36541. ><TD
  36542. ALIGN="CENTER"
  36543. ><B
  36544. >Warning</B
  36545. ></TD
  36546. ></TR
  36547. ><TR
  36548. ><TD
  36549. ALIGN="LEFT"
  36550. ><P
  36551. >      Complex arrays are sometimes rather copied than referenced. Thus following
  36552.      example will not work as expected.
  36553.      <TABLE
  36554. WIDTH="100%"
  36555. BORDER="0"
  36556. CELLPADDING="0"
  36557. CELLSPACING="0"
  36558. CLASS="EXAMPLE"
  36559. ><TR
  36560. ><TD
  36561. ><DIV
  36562. CLASS="example"
  36563. ><A
  36564. NAME="AEN5963"
  36565. ></A
  36566. ><P
  36567. ><B
  36568. >Example 21-3. References with complex arrays</B
  36569. ></P
  36570. ><TABLE
  36571. BORDER="0"
  36572. BGCOLOR="#E0E0E0"
  36573. CELLPADDING="5"
  36574. ><TR
  36575. ><TD
  36576. ><PRE
  36577. CLASS="php"
  36578. ><?php
  36579. $top = array(
  36580.     'A' => array(),
  36581.     'B' => array(
  36582.         'B_b' => array(),
  36583.     ),
  36584. );
  36585.  
  36586. $top['A']['parent'] = &$top;
  36587. $top['B']['parent'] = &$top;
  36588. $top['B']['B_b']['data'] = 'test';
  36589. print_r($top['A']['parent']['B']['B_b']); // array()
  36590. ?></PRE
  36591. ></TD
  36592. ></TR
  36593. ></TABLE
  36594. ></DIV
  36595. ></TD
  36596. ></TR
  36597. ></TABLE
  36598. >
  36599.     </P
  36600. ></TD
  36601. ></TR
  36602. ></TABLE
  36603. ></DIV
  36604. ><P
  36605. >     The second thing references do is to pass variables
  36606.     by-reference. This is done by making a local variable in a function and
  36607.     a variable in the calling scope reference to the same content. Example:
  36608.     <DIV
  36609. CLASS="informalexample"
  36610. ><P
  36611. ></P
  36612. ><A
  36613. NAME="AEN5967"
  36614. ></A
  36615. ><TABLE
  36616. BORDER="0"
  36617. BGCOLOR="#E0E0E0"
  36618. CELLPADDING="5"
  36619. ><TR
  36620. ><TD
  36621. ><PRE
  36622. CLASS="php"
  36623. ><?php
  36624. function foo(&$var)
  36625. {
  36626.     $var++;
  36627. }
  36628.  
  36629. $a=5;
  36630. foo($a);
  36631. ?></PRE
  36632. ></TD
  36633. ></TR
  36634. ></TABLE
  36635. ><P
  36636. ></P
  36637. ></DIV
  36638. >
  36639.     will make <VAR
  36640. CLASS="varname"
  36641. >$a</VAR
  36642. > to be 6. This happens because in
  36643.     the function <VAR
  36644. CLASS="varname"
  36645. >foo</VAR
  36646. > the variable
  36647.     <VAR
  36648. CLASS="varname"
  36649. >$var</VAR
  36650. > refers to the same content as
  36651.     <VAR
  36652. CLASS="varname"
  36653. >$a</VAR
  36654. >. See also more detailed explanations about <A
  36655. HREF="#language.references.pass"
  36656. >passing by reference</A
  36657. >.
  36658.    </P
  36659. ><P
  36660. >     The third thing reference can do is <A
  36661. HREF="#language.references.return"
  36662. >return by reference</A
  36663. >.
  36664.    </P
  36665. ></DIV
  36666. ><DIV
  36667. CLASS="sect1"
  36668. ><HR><H2
  36669. CLASS="sect1"
  36670. ><A
  36671. NAME="language.references.arent"
  36672. >What References Are Not</A
  36673. ></H2
  36674. ><P
  36675. >     As said before, references aren't pointers. That means, the
  36676.     following construct won't do what you expect:
  36677.     <DIV
  36678. CLASS="informalexample"
  36679. ><P
  36680. ></P
  36681. ><A
  36682. NAME="AEN5979"
  36683. ></A
  36684. ><TABLE
  36685. BORDER="0"
  36686. BGCOLOR="#E0E0E0"
  36687. CELLPADDING="5"
  36688. ><TR
  36689. ><TD
  36690. ><PRE
  36691. CLASS="php"
  36692. ><?php
  36693. function foo(&$var)
  36694. {
  36695.     $var =& $GLOBALS["baz"];
  36696. }
  36697. foo($bar); 
  36698. ?></PRE
  36699. ></TD
  36700. ></TR
  36701. ></TABLE
  36702. ><P
  36703. ></P
  36704. ></DIV
  36705. >
  36706.    </P
  36707. ><P
  36708. >     What happens is that <VAR
  36709. CLASS="varname"
  36710. >$var</VAR
  36711. > in
  36712.     <VAR
  36713. CLASS="varname"
  36714. >foo</VAR
  36715. > will be bound with
  36716.     <VAR
  36717. CLASS="varname"
  36718. >$bar</VAR
  36719. > in caller, but then it will be
  36720.     re-bound with <VAR
  36721. CLASS="varname"
  36722. >$GLOBALS["baz"]</VAR
  36723. >. There's no way
  36724.     to bind <VAR
  36725. CLASS="varname"
  36726. >$bar</VAR
  36727. > in the calling scope to something else
  36728.     using the reference mechanism, since <VAR
  36729. CLASS="varname"
  36730. >$bar</VAR
  36731. > is not
  36732.     available in the function <VAR
  36733. CLASS="varname"
  36734. >foo</VAR
  36735. > (it is represented by
  36736.     <VAR
  36737. CLASS="varname"
  36738. >$var</VAR
  36739. >, but <VAR
  36740. CLASS="varname"
  36741. >$var</VAR
  36742. > has only
  36743.     variable contents and not name-to-value binding in the calling
  36744.     symbol table).
  36745.     You can use <A
  36746. HREF="#language.references.return"
  36747. >returning
  36748.     references</A
  36749. > to reference variables selected by the function.
  36750.    </P
  36751. ></DIV
  36752. ><DIV
  36753. CLASS="sect1"
  36754. ><HR><H2
  36755. CLASS="sect1"
  36756. ><A
  36757. NAME="language.references.pass"
  36758. >Passing by Reference</A
  36759. ></H2
  36760. ><P
  36761. >    You can pass variable to function by reference, so that function could modify
  36762.    its arguments. The syntax is as follows:
  36763.     <DIV
  36764. CLASS="informalexample"
  36765. ><P
  36766. ></P
  36767. ><A
  36768. NAME="AEN5995"
  36769. ></A
  36770. ><TABLE
  36771. BORDER="0"
  36772. BGCOLOR="#E0E0E0"
  36773. CELLPADDING="5"
  36774. ><TR
  36775. ><TD
  36776. ><PRE
  36777. CLASS="php"
  36778. ><?php
  36779. function foo(&$var)
  36780. {
  36781.     $var++;
  36782. }
  36783.  
  36784. $a=5;
  36785. foo($a);
  36786. // $a is 6 here
  36787. ?></PRE
  36788. ></TD
  36789. ></TR
  36790. ></TABLE
  36791. ><P
  36792. ></P
  36793. ></DIV
  36794. >
  36795.   Note that there's no reference sign on function call - only on
  36796.   function definition. Function definition alone is enough to
  36797.   correctly pass the argument by reference. 
  36798.   </P
  36799. ><P
  36800. >   Following things can be passed by reference:
  36801.    <P
  36802. ></P
  36803. ><UL
  36804. ><LI
  36805. ><P
  36806. >       Variable, i.e. <VAR
  36807. CLASS="literal"
  36808. >foo($a)</VAR
  36809. >
  36810.      </P
  36811. ></LI
  36812. ><LI
  36813. ><P
  36814. >       New statement, i.e. <VAR
  36815. CLASS="literal"
  36816. >foo(new foobar())</VAR
  36817. >
  36818.      </P
  36819. ></LI
  36820. ><LI
  36821. ><P
  36822. >       Reference, returned from a function, i.e.:
  36823.     <DIV
  36824. CLASS="informalexample"
  36825. ><P
  36826. ></P
  36827. ><A
  36828. NAME="AEN6007"
  36829. ></A
  36830. ><TABLE
  36831. BORDER="0"
  36832. BGCOLOR="#E0E0E0"
  36833. CELLPADDING="5"
  36834. ><TR
  36835. ><TD
  36836. ><PRE
  36837. CLASS="php"
  36838. ><?php
  36839. function &bar()
  36840. {
  36841.     $a = 5;
  36842.     return $a;
  36843. }
  36844. foo(bar());
  36845. ?></PRE
  36846. ></TD
  36847. ></TR
  36848. ></TABLE
  36849. ><P
  36850. ></P
  36851. ></DIV
  36852. >
  36853.     See also explanations about <A
  36854. HREF="#language.references.return"
  36855. >returning by reference</A
  36856. >. 
  36857.      </P
  36858. ></LI
  36859. ></UL
  36860. >
  36861.   </P
  36862. ><P
  36863. >   Any other expression should not be passed by reference, as the
  36864.   result is undefined. For example, the following examples of passing
  36865.   by reference are invalid:
  36866.     <DIV
  36867. CLASS="informalexample"
  36868. ><P
  36869. ></P
  36870. ><A
  36871. NAME="AEN6011"
  36872. ></A
  36873. ><TABLE
  36874. BORDER="0"
  36875. BGCOLOR="#E0E0E0"
  36876. CELLPADDING="5"
  36877. ><TR
  36878. ><TD
  36879. ><PRE
  36880. CLASS="php"
  36881. ><?php
  36882. function bar() // Note the missing &
  36883. {
  36884.     $a = 5;
  36885.     return $a;
  36886. }
  36887. foo(bar());
  36888.  
  36889. foo($a = 5); // Expression, not variable
  36890. foo(5); // Constant, not variable
  36891. ?></PRE
  36892. ></TD
  36893. ></TR
  36894. ></TABLE
  36895. ><P
  36896. ></P
  36897. ></DIV
  36898. >
  36899.     These requirements are for PHP 4.0.4 and later.
  36900.   </P
  36901. ></DIV
  36902. ><DIV
  36903. CLASS="sect1"
  36904. ><HR><H2
  36905. CLASS="sect1"
  36906. ><A
  36907. NAME="language.references.return"
  36908. >Returning References</A
  36909. ></H2
  36910. ><P
  36911. >     Returning by-reference is useful when you want to use a function
  36912.     to find which variable a reference should be bound to. When
  36913.     returning references, use this syntax:
  36914.     <DIV
  36915. CLASS="informalexample"
  36916. ><P
  36917. ></P
  36918. ><A
  36919. NAME="AEN6016"
  36920. ></A
  36921. ><TABLE
  36922. BORDER="0"
  36923. BGCOLOR="#E0E0E0"
  36924. CELLPADDING="5"
  36925. ><TR
  36926. ><TD
  36927. ><PRE
  36928. CLASS="php"
  36929. ><?php
  36930. function &find_var($param)
  36931. {
  36932.     /* ...code... */
  36933.     return $found_var;
  36934. }
  36935.  
  36936. $foo =& find_var($bar);
  36937. $foo->x = 2;
  36938. ?></PRE
  36939. ></TD
  36940. ></TR
  36941. ></TABLE
  36942. ><P
  36943. ></P
  36944. ></DIV
  36945. >
  36946.     In this example, the property of the object returned by the
  36947.     <VAR
  36948. CLASS="varname"
  36949. >find_var</VAR
  36950. > function would be set, not the
  36951.     copy, as it would be without using reference syntax.
  36952.    </P
  36953. ><DIV
  36954. CLASS="note"
  36955. ><BLOCKQUOTE
  36956. CLASS="note"
  36957. ><P
  36958. ><B
  36959. >Note: </B
  36960. >
  36961.      Unlike parameter passing, here you have to use
  36962.      <VAR
  36963. CLASS="literal"
  36964. >&</VAR
  36965. > in both places - to indicate that you
  36966.      return by-reference, not a copy as usual, and to indicate that
  36967.      reference binding, rather than usual assignment, should be done
  36968.      for <VAR
  36969. CLASS="varname"
  36970. >$foo</VAR
  36971. >.
  36972.     </P
  36973. ></BLOCKQUOTE
  36974. ></DIV
  36975. ></DIV
  36976. ><DIV
  36977. CLASS="sect1"
  36978. ><HR><H2
  36979. CLASS="sect1"
  36980. ><A
  36981. NAME="language.references.unset"
  36982. >Unsetting References</A
  36983. ></H2
  36984. ><P
  36985. >     When you unset the reference, you just break the binding between
  36986.     variable name and variable content. This does not mean that
  36987.     variable content will be destroyed. For example:
  36988.     <DIV
  36989. CLASS="informalexample"
  36990. ><P
  36991. ></P
  36992. ><A
  36993. NAME="AEN6026"
  36994. ></A
  36995. ><TABLE
  36996. BORDER="0"
  36997. BGCOLOR="#E0E0E0"
  36998. CELLPADDING="5"
  36999. ><TR
  37000. ><TD
  37001. ><PRE
  37002. CLASS="php"
  37003. ><?php
  37004. $a = 1;
  37005. $b =& $a;
  37006. unset($a); 
  37007. ?></PRE
  37008. ></TD
  37009. ></TR
  37010. ></TABLE
  37011. ><P
  37012. ></P
  37013. ></DIV
  37014. >
  37015.     won't unset <VAR
  37016. CLASS="varname"
  37017. >$b</VAR
  37018. >, just <VAR
  37019. CLASS="varname"
  37020. >$a</VAR
  37021. >. 
  37022.    </P
  37023. ><P
  37024. >     Again, it might be useful to think about this as analogous to Unix
  37025.     <B
  37026. CLASS="command"
  37027. >unlink</B
  37028. > call.
  37029.    </P
  37030. ></DIV
  37031. ><DIV
  37032. CLASS="sect1"
  37033. ><HR><H2
  37034. CLASS="sect1"
  37035. ><A
  37036. NAME="language.references.spot"
  37037. >Spotting References</A
  37038. ></H2
  37039. ><P
  37040. >     Many syntax constructs in PHP are implemented via referencing
  37041.     mechanisms, so everything told above about reference binding also
  37042.     apply to these constructs. Some constructs, like passing and
  37043.     returning by-reference, are mentioned above. Other constructs that
  37044.     use references are:
  37045.    </P
  37046. ><DIV
  37047. CLASS="sect2"
  37048. ><HR><H3
  37049. CLASS="sect2"
  37050. ><A
  37051. NAME="references.global"
  37052. ><VAR
  37053. CLASS="literal"
  37054. >global</VAR
  37055. > References</A
  37056. ></H3
  37057. ><P
  37058. >      When you declare variable as <B
  37059. CLASS="command"
  37060. >global $var</B
  37061. > you
  37062.      are in fact creating reference to a global variable. That means,
  37063.      this is the same as:
  37064.      <DIV
  37065. CLASS="informalexample"
  37066. ><P
  37067. ></P
  37068. ><A
  37069. NAME="AEN6040"
  37070. ></A
  37071. ><TABLE
  37072. BORDER="0"
  37073. BGCOLOR="#E0E0E0"
  37074. CELLPADDING="5"
  37075. ><TR
  37076. ><TD
  37077. ><PRE
  37078. CLASS="php"
  37079. ><?php
  37080. $var =& $GLOBALS["var"];
  37081. ?></PRE
  37082. ></TD
  37083. ></TR
  37084. ></TABLE
  37085. ><P
  37086. ></P
  37087. ></DIV
  37088. >
  37089.     </P
  37090. ><P
  37091. >      That means, for example, that unsetting <VAR
  37092. CLASS="varname"
  37093. >$var</VAR
  37094. >
  37095.      won't unset global variable.
  37096.     </P
  37097. ></DIV
  37098. ><DIV
  37099. CLASS="sect2"
  37100. ><HR><H3
  37101. CLASS="sect2"
  37102. ><A
  37103. NAME="references.this"
  37104. ><VAR
  37105. CLASS="literal"
  37106. >$this</VAR
  37107. ></A
  37108. ></H3
  37109. ><P
  37110. >      In an object method, <VAR
  37111. CLASS="varname"
  37112. >$this</VAR
  37113. > is always reference
  37114.      to the caller object.
  37115.     </P
  37116. ></DIV
  37117. ></DIV
  37118. ></DIV
  37119. ></DIV
  37120. ><DIV
  37121. CLASS="PART"
  37122. ><A
  37123. NAME="security"
  37124. ></A
  37125. ><DIV
  37126. CLASS="TITLEPAGE"
  37127. ><H1
  37128. CLASS="title"
  37129. >IV. Security</H1
  37130. ><DIV
  37131. CLASS="TOC"
  37132. ><DL
  37133. ><DT
  37134. ><B
  37135. >Table of Contents</B
  37136. ></DT
  37137. ><DT
  37138. >22. <A
  37139. HREF="#security.intro"
  37140. >Introduction</A
  37141. ></DT
  37142. ><DT
  37143. >23. <A
  37144. HREF="#security.general"
  37145. >General considerations</A
  37146. ></DT
  37147. ><DT
  37148. >24. <A
  37149. HREF="#security.cgi-bin"
  37150. >Installed as CGI binary</A
  37151. ></DT
  37152. ><DT
  37153. >25. <A
  37154. HREF="#security.apache"
  37155. >Installed as an Apache module</A
  37156. ></DT
  37157. ><DT
  37158. >26. <A
  37159. HREF="#security.filesystem"
  37160. >Filesystem Security</A
  37161. ></DT
  37162. ><DT
  37163. >27. <A
  37164. HREF="#security.database"
  37165. >Database Security</A
  37166. ></DT
  37167. ><DT
  37168. >28. <A
  37169. HREF="#security.errors"
  37170. >Error Reporting</A
  37171. ></DT
  37172. ><DT
  37173. >29. <A
  37174. HREF="#security.globals"
  37175. >Using Register Globals</A
  37176. ></DT
  37177. ><DT
  37178. >30. <A
  37179. HREF="#security.variables"
  37180. >User Submitted Data</A
  37181. ></DT
  37182. ><DT
  37183. >31. <A
  37184. HREF="#security.magicquotes"
  37185. >Magic Quotes</A
  37186. ></DT
  37187. ><DT
  37188. >32. <A
  37189. HREF="#security.hiding"
  37190. >Hiding PHP</A
  37191. ></DT
  37192. ><DT
  37193. >33. <A
  37194. HREF="#security.current"
  37195. >Keeping Current</A
  37196. ></DT
  37197. ></DL
  37198. ></DIV
  37199. ></DIV
  37200. ><DIV
  37201. CLASS="chapter"
  37202. ><HR><H1
  37203. ><A
  37204. NAME="security.intro"
  37205. >Chapter 22. Introduction</A
  37206. ></H1
  37207. ><P
  37208. >    PHP is a powerful language and the interpreter, whether included
  37209.    in a web server as a module or executed as a separate
  37210.    <ACRONYM
  37211. CLASS="acronym"
  37212. >CGI</ACRONYM
  37213. > binary, is able to access files, execute
  37214.    commands and open network connections on the server.  These
  37215.    properties make anything run on a web server insecure by default.
  37216.    PHP is designed specifically to be a more secure language for
  37217.    writing CGI programs than Perl or C, and with correct selection of
  37218.    compile-time and runtime configuration options, and proper coding
  37219.    practices, it can give you exactly the combination of freedom and
  37220.    security you need.
  37221.   </P
  37222. ><P
  37223. >    As there are many different ways of utilizing PHP, there are many
  37224.    configuration options controlling its behaviour.  A large
  37225.    selection of options guarantees you can use PHP for a lot of
  37226.    purposes, but it also means there are combinations of these
  37227.    options and server configurations that result in an insecure
  37228.    setup.
  37229.   </P
  37230. ><P
  37231. >    The configuration flexibility of PHP is equally rivalled by the
  37232.    code flexibility. PHP can be used to build complete server
  37233.    applications, with all the power of a shell user, or it can be used
  37234.    for simple server-side includes with little risk in a tightly
  37235.    controlled environment. How you build that environment, and how
  37236.    secure it is, is largely up to the PHP developer.
  37237.   </P
  37238. ><P
  37239. >    This chapter starts with some general security advice, explains
  37240.    the different configuration option combinations and the situations
  37241.    they can be safely used, and describes different considerations in
  37242.    coding for different levels of security.
  37243.   </P
  37244. ></DIV
  37245. ><DIV
  37246. CLASS="chapter"
  37247. ><HR><H1
  37248. ><A
  37249. NAME="security.general"
  37250. >Chapter 23. General considerations</A
  37251. ></H1
  37252. ><P
  37253. >     A completely secure system is a virtual impossibility, so an
  37254.     approach often used in the security profession is one of balancing
  37255.     risk and usability. If every variable submitted by a user required
  37256.     two forms of biometric validation (such as a retinal scan and a
  37257.     fingerprint), you would have an extremely high level of
  37258.     accountability. It would also take half an hour to fill out a fairly
  37259.     complex form, which would tend to encourage users to find ways of
  37260.     bypassing the security.
  37261.    </P
  37262. ><P
  37263. >     The best security is often unobtrusive enough to suit the
  37264.     requirements without the user being prevented from accomplishing
  37265.     their work, or over-burdening the code author with excessive
  37266.     complexity. Indeed, some security attacks are merely exploits of
  37267.     this kind of overly built security, which tends to erode over time.
  37268.    </P
  37269. ><P
  37270. >     A phrase worth remembering: A system is only as good as the weakest
  37271.     link in a chain. If all transactions are heavily logged based on
  37272.     time, location, transaction type, etc. but the user is only
  37273.     verified based on a single cookie, the validity of tying the users
  37274.     to the transaction log is severely weakened.
  37275.    </P
  37276. ><P
  37277. >     When testing, keep in mind that you will not be able to test all
  37278.     possibilities for even the simplest of pages. The input you
  37279.     may expect will be completely unrelated to the input given by
  37280.     a disgruntled employee, a cracker with months of time on their
  37281.     hands, or a housecat walking across the keyboard. This is why it's
  37282.     best to look at the code from a logical perspective, to discern
  37283.     where unexpected data can be introduced, and then follow how it is
  37284.     modified, reduced, or amplified.
  37285.    </P
  37286. ><P
  37287. >     The Internet is filled with people trying to make a name for
  37288.     themselves by breaking your code, crashing your site, posting
  37289.     inappropriate content, and otherwise making your day interesting.
  37290.     It doesn't matter if you have a small or large site, you are
  37291.     a target by simply being online, by having a server that can be
  37292.     connected to. Many cracking programs do not discern by size, they
  37293.     simply trawl massive IP blocks looking for victims. Try not to
  37294.     become one.
  37295.    </P
  37296. ></DIV
  37297. ><DIV
  37298. CLASS="chapter"
  37299. ><HR><H1
  37300. ><A
  37301. NAME="security.cgi-bin"
  37302. >Chapter 24. Installed as CGI binary</A
  37303. ></H1
  37304. ><DIV
  37305. CLASS="sect1"
  37306. ><H2
  37307. CLASS="sect1"
  37308. ><A
  37309. NAME="security.cgi-bin.attacks"
  37310. >Possible attacks</A
  37311. ></H2
  37312. ><P
  37313. >      Using PHP as a <ACRONYM
  37314. CLASS="acronym"
  37315. >CGI</ACRONYM
  37316. > binary is an option for
  37317.      setups that for some reason do not wish to integrate PHP as a
  37318.      module into server software (like Apache), or will use PHP with
  37319.      different kinds of CGI wrappers to create safe chroot and setuid
  37320.      environments for scripts.  This setup usually involves installing
  37321.      executable PHP binary to the web server cgi-bin directory.  CERT
  37322.      advisory <A
  37323. HREF="http://www.cert.org/advisories/CA-1996-11.html"
  37324. TARGET="_top"
  37325. >CA-96.11</A
  37326. > recommends
  37327.      against placing any interpreters into cgi-bin.  Even if the PHP
  37328.      binary can be used as a standalone interpreter, PHP is designed
  37329.      to prevent the attacks this setup makes possible:
  37330.     </P
  37331. ><P
  37332. ></P
  37333. ><UL
  37334. ><LI
  37335. ><P
  37336. >        Accessing system files: <TT
  37337. CLASS="filename"
  37338. >http://my.host/cgi-bin/php?/etc/passwd</TT
  37339. >
  37340.       </P
  37341. ><P
  37342. >        The query information in a URL after the question mark (?)  is
  37343.        passed as command line arguments to the interpreter by the CGI
  37344.        interface.  Usually interpreters open and execute the file
  37345.        specified as the first argument on the command line.
  37346.       </P
  37347. ><P
  37348. >        When invoked as a CGI binary, PHP refuses to interpret the
  37349.        command line arguments.
  37350.       </P
  37351. ></LI
  37352. ><LI
  37353. ><P
  37354. >        Accessing any web document on server: <TT
  37355. CLASS="filename"
  37356. >http://my.host/cgi-bin/php/secret/doc.html</TT
  37357. >
  37358.       </P
  37359. ><P
  37360. >        The path information part of the URL after the PHP binary name,
  37361.        <TT
  37362. CLASS="filename"
  37363. >/secret/doc.html</TT
  37364. > is
  37365.        conventionally used to specify the name of the file to be
  37366.        opened and interpreted by the <ACRONYM
  37367. CLASS="acronym"
  37368. >CGI</ACRONYM
  37369. > program.
  37370.        Usually some web server configuration directives (Apache:
  37371.        Action) are used to redirect requests to documents like
  37372.        <TT
  37373. CLASS="filename"
  37374. >http://my.host/secret/script.php</TT
  37375. > to the
  37376.        PHP interpreter.  With this setup, the web server first checks
  37377.        the access permissions to the directory <TT
  37378. CLASS="filename"
  37379. >/secret</TT
  37380. >, and after that creates the
  37381.        redirected request <TT
  37382. CLASS="filename"
  37383. >http://my.host/cgi-bin/php/secret/script.php</TT
  37384. >.
  37385.        Unfortunately, if the request is originally given in this form,
  37386.        no access checks are made by web server for file <TT
  37387. CLASS="filename"
  37388. >/secret/script.php</TT
  37389. >, but only for the
  37390.        <TT
  37391. CLASS="filename"
  37392. >/cgi-bin/php</TT
  37393. > file.  This way
  37394.        any user able to access <TT
  37395. CLASS="filename"
  37396. >/cgi-bin/php</TT
  37397. > is able to access any
  37398.        protected document on the web server.
  37399.       </P
  37400. ><P
  37401. >        In PHP, compile-time configuration option <A
  37402. HREF="#configure.enable-force-cgi-redirect"
  37403. >--enable-force-cgi-redirect</A
  37404. >
  37405.        and runtime configuration directives <A
  37406. HREF="#ini.doc-root"
  37407. >doc_root</A
  37408. > and <A
  37409. HREF="#ini.user-dir"
  37410. >user_dir</A
  37411. > can be used to prevent
  37412.        this attack, if the server document tree has any directories
  37413.        with access restrictions.  See below for full the explanation
  37414.        of the different combinations.
  37415.       </P
  37416. ></LI
  37417. ></UL
  37418. ></DIV
  37419. ><DIV
  37420. CLASS="sect1"
  37421. ><HR><H2
  37422. CLASS="sect1"
  37423. ><A
  37424. NAME="security.cgi-bin.default"
  37425. >Case 1: only public files served</A
  37426. ></H2
  37427. ><P
  37428. >      If your server does not have any content that is not restricted
  37429.      by password or ip based access control, there is no need for
  37430.      these configuration options.  If your web server does not allow
  37431.      you to do redirects, or the server does not have a way to
  37432.      communicate to the PHP binary that the request is a safely
  37433.      redirected request, you can specify the option <A
  37434. HREF="#configure.enable-force-cgi-redirect"
  37435. >--enable-force-cgi-redirect</A
  37436. >
  37437.      to the configure script.  You still have to make sure your PHP
  37438.      scripts do not rely on one or another way of calling the script,
  37439.      neither by directly <TT
  37440. CLASS="filename"
  37441. >http://my.host/cgi-bin/php/dir/script.php</TT
  37442. >
  37443.      nor by redirection <TT
  37444. CLASS="filename"
  37445. >http://my.host/dir/script.php</TT
  37446. >.
  37447.     </P
  37448. ><P
  37449. >      Redirection can be configured in Apache by using AddHandler and
  37450.      Action directives (see below).
  37451.     </P
  37452. ></DIV
  37453. ><DIV
  37454. CLASS="sect1"
  37455. ><HR><H2
  37456. CLASS="sect1"
  37457. ><A
  37458. NAME="security.cgi-bin.force-redirect"
  37459. >Case 2: using --enable-force-cgi-redirect</A
  37460. ></H2
  37461. ><P
  37462. >      This compile-time option prevents anyone from calling PHP
  37463.      directly with a URL like <TT
  37464. CLASS="filename"
  37465. >http://my.host/cgi-bin/php/secretdir/script.php</TT
  37466. >.
  37467.      Instead, PHP will only parse in this mode if it has gone through
  37468.      a web server redirect rule.
  37469.     </P
  37470. ><P
  37471. >      Usually the redirection in the Apache configuration is done with
  37472.      the following directives:
  37473.     </P
  37474. ><TABLE
  37475. BORDER="0"
  37476. BGCOLOR="#E0E0E0"
  37477. CELLPADDING="5"
  37478. ><TR
  37479. ><TD
  37480. ><PRE
  37481. CLASS="apache-conf"
  37482. >Action php-script /cgi-bin/php
  37483. AddHandler php-script .php</PRE
  37484. ></TD
  37485. ></TR
  37486. ></TABLE
  37487. ><P
  37488. >      This option has only been tested with the Apache web server, and
  37489.      relies on Apache to set the non-standard CGI environment variable
  37490.      <VAR
  37491. CLASS="envar"
  37492. >REDIRECT_STATUS</VAR
  37493. > on redirected requests.  If your
  37494.      web server does not support any way of telling if the request is
  37495.      direct or redirected, you cannot use this option and you must use
  37496.      one of the other ways of running the CGI version documented
  37497.      here.
  37498.     </P
  37499. ></DIV
  37500. ><DIV
  37501. CLASS="sect1"
  37502. ><HR><H2
  37503. CLASS="sect1"
  37504. ><A
  37505. NAME="security.cgi-bin.doc-root"
  37506. >Case 3: setting doc_root or user_dir</A
  37507. ></H2
  37508. ><P
  37509. >      To include active content, like scripts and executables, in the
  37510.      web server document directories is sometimes considered an insecure
  37511.      practice.  If, because of some configuration mistake, the scripts
  37512.      are not executed but displayed as regular HTML documents, this
  37513.      may result in leakage of intellectual property or security
  37514.      information like passwords.  Therefore many sysadmins will prefer
  37515.      setting up another directory structure for scripts that are
  37516.      accessible only through the PHP CGI, and therefore always
  37517.      interpreted and not displayed as such.
  37518.     </P
  37519. ><P
  37520. >      Also if the method for making sure the requests are not
  37521.      redirected, as described in the previous section, is not
  37522.      available, it is necessary to set up a script doc_root that is
  37523.      different from web document root.
  37524.     </P
  37525. ><P
  37526. >      You can set the PHP script document root by the configuration
  37527.      directive <A
  37528. HREF="#ini.doc-root"
  37529. >doc_root</A
  37530. > in the
  37531.      <A
  37532. HREF="#configuration.file"
  37533. >configuration file</A
  37534. >, or
  37535.      you can set the environment variable
  37536.      <VAR
  37537. CLASS="envar"
  37538. >PHP_DOCUMENT_ROOT</VAR
  37539. >.  If it is set, the CGI version
  37540.      of PHP will always construct the file name to open with this
  37541.      <VAR
  37542. CLASS="parameter"
  37543. >doc_root</VAR
  37544. > and the path information in the
  37545.      request, so you can be sure no script is executed outside this
  37546.      directory (except for <VAR
  37547. CLASS="parameter"
  37548. >user_dir</VAR
  37549. >
  37550.      below).
  37551.     </P
  37552. ><P
  37553. >      Another option usable here is <A
  37554. HREF="#ini.user-dir"
  37555. >user_dir</A
  37556. >.  When user_dir is unset,
  37557.      only thing controlling the opened file name is
  37558.      <VAR
  37559. CLASS="parameter"
  37560. >doc_root</VAR
  37561. >.  Opening a URL like <TT
  37562. CLASS="filename"
  37563. >http://my.host/~user/doc.php</TT
  37564. > does not
  37565.      result in opening a file under users home directory, but a file
  37566.      called <TT
  37567. CLASS="filename"
  37568. >~user/doc.php</TT
  37569. > under
  37570.      doc_root (yes, a directory name starting with a tilde
  37571.      [<VAR
  37572. CLASS="literal"
  37573. >~</VAR
  37574. >]).
  37575.     </P
  37576. ><P
  37577. >      If user_dir is set to for example <TT
  37578. CLASS="filename"
  37579. >public_php</TT
  37580. >, a request like <TT
  37581. CLASS="filename"
  37582. >http://my.host/~user/doc.php</TT
  37583. > will open a
  37584.      file called <TT
  37585. CLASS="filename"
  37586. >doc.php</TT
  37587. > under the directory
  37588.      named <TT
  37589. CLASS="filename"
  37590. >public_php</TT
  37591. > under the home
  37592.      directory of the user.  If the home of the user is <TT
  37593. CLASS="filename"
  37594. >/home/user</TT
  37595. >, the file executed is
  37596.      <TT
  37597. CLASS="filename"
  37598. >/home/user/public_php/doc.php</TT
  37599. >.
  37600.     </P
  37601. ><P
  37602. >      <VAR
  37603. CLASS="parameter"
  37604. >user_dir</VAR
  37605. > expansion happens regardless of
  37606.      the <VAR
  37607. CLASS="parameter"
  37608. >doc_root</VAR
  37609. > setting, so you can control
  37610.      the document root and user directory access
  37611.      separately.
  37612.     </P
  37613. ></DIV
  37614. ><DIV
  37615. CLASS="sect1"
  37616. ><HR><H2
  37617. CLASS="sect1"
  37618. ><A
  37619. NAME="security.cgi-bin.shell"
  37620. >Case 4: PHP parser outside of web tree</A
  37621. ></H2
  37622. ><P
  37623. >      A very secure option is to put the PHP parser binary somewhere
  37624.      outside of the web tree of files.  In <TT
  37625. CLASS="filename"
  37626. >/usr/local/bin</TT
  37627. >, for example.  The only real
  37628.      downside to this option is that you will now have to put a line
  37629.      similar to:
  37630.      <DIV
  37631. CLASS="informalexample"
  37632. ><P
  37633. ></P
  37634. ><A
  37635. NAME="AEN6139"
  37636. ></A
  37637. ><TABLE
  37638. BORDER="0"
  37639. BGCOLOR="#E0E0E0"
  37640. CELLPADDING="5"
  37641. ><TR
  37642. ><TD
  37643. ><PRE
  37644. CLASS="programlisting"
  37645. >#!/usr/local/bin/php</PRE
  37646. ></TD
  37647. ></TR
  37648. ></TABLE
  37649. ><P
  37650. ></P
  37651. ></DIV
  37652. >
  37653.      as the first line of any file containing PHP tags.  You will also
  37654.      need to make the file executable.  That is, treat it exactly as
  37655.      you would treat any other CGI script written in Perl or sh or any
  37656.      other common scripting language which uses the
  37657.      <VAR
  37658. CLASS="literal"
  37659. >#!</VAR
  37660. > shell-escape mechanism for launching
  37661.      itself.
  37662.     </P
  37663. ><P
  37664. >      To get PHP to handle <VAR
  37665. CLASS="envar"
  37666. >PATH_INFO</VAR
  37667. > and
  37668.      <VAR
  37669. CLASS="envar"
  37670. >PATH_TRANSLATED</VAR
  37671. > information correctly with this
  37672.      setup, the PHP parser should be compiled with the <A
  37673. HREF="#configure.enable-discard-path"
  37674. >--enable-discard-path</A
  37675. >
  37676.      configure option.
  37677.     </P
  37678. ></DIV
  37679. ></DIV
  37680. ><DIV
  37681. CLASS="chapter"
  37682. ><HR><H1
  37683. ><A
  37684. NAME="security.apache"
  37685. >Chapter 25. Installed as an Apache module</A
  37686. ></H1
  37687. ><P
  37688. >     When PHP is used as an Apache module it inherits Apache's user
  37689.     permissions (typically those of the "nobody" user). This has several
  37690.     impacts on security and authorization. For example, if you are using
  37691.     PHP to access a database, unless that database has built-in access
  37692.     control, you will have to make the database accessible to the
  37693.     "nobody" user. This means a malicious script could access and modify
  37694.     the database, even without a username and password. It's entirely
  37695.     possible that a web spider could stumble across a database
  37696.     administrator's web page, and drop all of your databases. You can
  37697.     protect against this with Apache authorization, or you can design
  37698.     your own access model using LDAP, <TT
  37699. CLASS="filename"
  37700. >.htaccess</TT
  37701. > files, etc. and include
  37702.     that code as part of your PHP scripts.
  37703.    </P
  37704. ><P
  37705. >     Often, once security is established to the point where the PHP user
  37706.     (in this case, the apache user) has very little risk attached to it,
  37707.     it is discovered that PHP is now prevented from writing any files
  37708.     to user directories. Or perhaps it has been prevented from accessing
  37709.     or changing databases. It has equally been secured from writing
  37710.     good and bad files, or entering good and bad database transactions.
  37711.    </P
  37712. ><P
  37713. >     A frequent security mistake made at this point is to allow apache
  37714.     root permissions, or to escalate apache's abilities in some other
  37715.     way.
  37716.    </P
  37717. ><P
  37718. >     Escalating the Apache user's permissions to root is extremely
  37719.     dangerous and may compromise the entire system, so sudo'ing,
  37720.     chroot'ing, or otherwise running as root should not be considered by
  37721.     those who are not security professionals.
  37722.    </P
  37723. ><P
  37724. >     There are some simpler solutions. By using
  37725.     <A
  37726. HREF="#ini.open-basedir"
  37727. >open_basedir</A
  37728. > you can control and restrict what
  37729.     directories are allowed to be used for PHP. You can also set up
  37730.     apache-only areas, to restrict all web based activity to non-user,
  37731.     or non-system, files.
  37732.    </P
  37733. ></DIV
  37734. ><DIV
  37735. CLASS="chapter"
  37736. ><HR><H1
  37737. ><A
  37738. NAME="security.filesystem"
  37739. >Chapter 26. Filesystem Security</A
  37740. ></H1
  37741. ><P
  37742. >     PHP is subject to the security built into most server systems with
  37743.     respect to permissions on a file and directory basis. This allows
  37744.     you to control which files in the filesystem may be read. Care
  37745.     should be taken with any files which are world readable to ensure
  37746.     that they are safe for reading by all users who have access to that
  37747.     filesystem.
  37748.    </P
  37749. ><P
  37750. >     Since PHP was designed to allow user level access to the filesystem,
  37751.     it's entirely possible to write a PHP script that will allow you
  37752.     to read system files such as /etc/passwd, modify your ethernet
  37753.     connections, send massive printer jobs out, etc. This has some
  37754.     obvious implications, in that you need to ensure that the files
  37755.     that you read from and write to are the appropriate ones.
  37756.    </P
  37757. ><P
  37758. >     Consider the following script, where a user indicates that they'd
  37759.     like to delete a file in their home directory. This assumes a
  37760.     situation where a PHP web interface is regularly used for file
  37761.     management, so the Apache user is allowed to delete files in
  37762.     the user home directories.
  37763.    </P
  37764. ><P
  37765. >     <TABLE
  37766. WIDTH="100%"
  37767. BORDER="0"
  37768. CELLPADDING="0"
  37769. CELLSPACING="0"
  37770. CLASS="EXAMPLE"
  37771. ><TR
  37772. ><TD
  37773. ><DIV
  37774. CLASS="example"
  37775. ><A
  37776. NAME="AEN6161"
  37777. ></A
  37778. ><P
  37779. ><B
  37780. >Example 26-1. Poor variable checking leads to....</B
  37781. ></P
  37782. ><TABLE
  37783. BORDER="0"
  37784. BGCOLOR="#E0E0E0"
  37785. CELLPADDING="5"
  37786. ><TR
  37787. ><TD
  37788. ><PRE
  37789. CLASS="php"
  37790. ><?php
  37791. // remove a file from the user's home directory
  37792. $username = $_POST['user_submitted_name'];
  37793. $homedir = "/home/$username";
  37794. $file_to_delete = "$userfile";
  37795. unlink ("$homedir/$userfile");
  37796. echo "$file_to_delete has been deleted!";
  37797. ?></PRE
  37798. ></TD
  37799. ></TR
  37800. ></TABLE
  37801. ></DIV
  37802. ></TD
  37803. ></TR
  37804. ></TABLE
  37805. >
  37806.    Since the username is postable from a user form, they can submit
  37807.    a username and file belonging to someone else, and delete files.
  37808.    In this case, you'd want to use some other form of authentication.
  37809.    Consider what could happen if the variables submitted were
  37810.    "../etc/" and "passwd". The code would then effectively read:
  37811.     <TABLE
  37812. WIDTH="100%"
  37813. BORDER="0"
  37814. CELLPADDING="0"
  37815. CELLSPACING="0"
  37816. CLASS="EXAMPLE"
  37817. ><TR
  37818. ><TD
  37819. ><DIV
  37820. CLASS="example"
  37821. ><A
  37822. NAME="AEN6164"
  37823. ></A
  37824. ><P
  37825. ><B
  37826. >Example 26-2. ... A filesystem attack</B
  37827. ></P
  37828. ><TABLE
  37829. BORDER="0"
  37830. BGCOLOR="#E0E0E0"
  37831. CELLPADDING="5"
  37832. ><TR
  37833. ><TD
  37834. ><PRE
  37835. CLASS="php"
  37836. ><?php
  37837. // removes a file from anywhere on the hard drive that
  37838. // the PHP user has access to. If PHP has root access:
  37839. $username = "../etc/";
  37840. $homedir = "/home/../etc/";
  37841. $file_to_delete = "passwd";
  37842. unlink ("/home/../etc/passwd");
  37843. echo "/home/../etc/passwd has been deleted!";
  37844. ?></PRE
  37845. ></TD
  37846. ></TR
  37847. ></TABLE
  37848. ></DIV
  37849. ></TD
  37850. ></TR
  37851. ></TABLE
  37852. >
  37853.     There are two important measures you should take to prevent these
  37854.     issues.
  37855.     <P
  37856. ></P
  37857. ><UL
  37858. ><LI
  37859. ><P
  37860. >        Only allow limited permissions to the PHP web user binary.
  37861.       </P
  37862. ></LI
  37863. ><LI
  37864. ><P
  37865. >        Check all variables which are submitted.
  37866.       </P
  37867. ></LI
  37868. ></UL
  37869. >
  37870.     Here is an improved script:
  37871.     <TABLE
  37872. WIDTH="100%"
  37873. BORDER="0"
  37874. CELLPADDING="0"
  37875. CELLSPACING="0"
  37876. CLASS="EXAMPLE"
  37877. ><TR
  37878. ><TD
  37879. ><DIV
  37880. CLASS="example"
  37881. ><A
  37882. NAME="AEN6172"
  37883. ></A
  37884. ><P
  37885. ><B
  37886. >Example 26-3. More secure file name checking</B
  37887. ></P
  37888. ><TABLE
  37889. BORDER="0"
  37890. BGCOLOR="#E0E0E0"
  37891. CELLPADDING="5"
  37892. ><TR
  37893. ><TD
  37894. ><PRE
  37895. CLASS="php"
  37896. ><?php
  37897. // removes a file from the hard drive that
  37898. // the PHP user has access to.
  37899. $username = $_SERVER['REMOTE_USER']; // using an authentication mechanisim
  37900.  
  37901. $homedir = "/home/$username";
  37902.  
  37903. $file_to_delete = basename("$userfile"); // strip paths
  37904. unlink ($homedir/$file_to_delete);
  37905.  
  37906. $fp = fopen("/home/logging/filedelete.log","+a"); //log the deletion
  37907. $logstring = "$username $homedir $file_to_delete";
  37908. fwrite ($fp, $logstring);
  37909. fclose($fp);
  37910.  
  37911. echo "$file_to_delete has been deleted!";
  37912. ?></PRE
  37913. ></TD
  37914. ></TR
  37915. ></TABLE
  37916. ></DIV
  37917. ></TD
  37918. ></TR
  37919. ></TABLE
  37920. >
  37921.     However, even this is not without it's flaws. If your authentication
  37922.     system allowed users to create their own user logins, and a user
  37923.     chose the login "../etc/", the system is once again exposed. For
  37924.     this reason, you may prefer to write a more customized check:
  37925.     <TABLE
  37926. WIDTH="100%"
  37927. BORDER="0"
  37928. CELLPADDING="0"
  37929. CELLSPACING="0"
  37930. CLASS="EXAMPLE"
  37931. ><TR
  37932. ><TD
  37933. ><DIV
  37934. CLASS="example"
  37935. ><A
  37936. NAME="AEN6175"
  37937. ></A
  37938. ><P
  37939. ><B
  37940. >Example 26-4. More secure file name checking</B
  37941. ></P
  37942. ><TABLE
  37943. BORDER="0"
  37944. BGCOLOR="#E0E0E0"
  37945. CELLPADDING="5"
  37946. ><TR
  37947. ><TD
  37948. ><PRE
  37949. CLASS="php"
  37950. ><?php
  37951. $username = $_SERVER['REMOTE_USER']; // using an authentication mechanisim
  37952. $homedir = "/home/$username";
  37953.  
  37954. if (!ereg('^[^./][^/]*$', $userfile))
  37955.      die('bad filename'); //die, do not process
  37956.  
  37957. if (!ereg('^[^./][^/]*$', $username))
  37958.      die('bad username'); //die, do not process
  37959. //etc...
  37960. ?></PRE
  37961. ></TD
  37962. ></TR
  37963. ></TABLE
  37964. ></DIV
  37965. ></TD
  37966. ></TR
  37967. ></TABLE
  37968. >
  37969.    </P
  37970. ><P
  37971. >     Depending on your operating system, there are a wide variety of files
  37972.     which you should be concerned about, including device entries (/dev/
  37973.     or COM1), configuration files (/etc/ files and the .ini files),
  37974.     well known file storage areas (/home/, My Documents), etc. For this
  37975.     reason, it's usually easier to create a policy where you forbid
  37976.     everything except for what you explicitly allow.
  37977.    </P
  37978. ></DIV
  37979. ><DIV
  37980. CLASS="chapter"
  37981. ><HR><H1
  37982. ><A
  37983. NAME="security.database"
  37984. >Chapter 27. Database Security</A
  37985. ></H1
  37986. ><P
  37987. >     Nowadays, databases are cardinal components of any web based application by
  37988.     enabling websites to provide varying dynamic content. Since very sensitive
  37989.     or secret information can be stored in a database, you should strongly
  37990.     consider protecting your databases.
  37991.    </P
  37992. ><P
  37993. >     To retrieve or to store any information you need to connect to the database,
  37994.     send a legitimate query, fetch the result, and close the connection.
  37995.     Nowadays, the commonly used query language in this interaction is the
  37996.     Structured Query Language (SQL). See how an attacker can <A
  37997. HREF="#security.database.sql-injection"
  37998. >tamper with an SQL query</A
  37999. >.
  38000.    </P
  38001. ><P
  38002. >     As you can surmise, PHP cannot protect your database by itself. The
  38003.     following sections aim to be an introduction into the very basics of how to
  38004.     access and manipulate databases within PHP scripts.
  38005.    </P
  38006. ><P
  38007. >     Keep in mind this simple rule: defense in depth. The more places you
  38008.     take action to increase the protection of your database, the less
  38009.     probability of an attacker succeeding in exposing or abusing any stored
  38010.     information. Good design of the database schema and the application
  38011.     deals with your greatest fears.
  38012.    </P
  38013. ><DIV
  38014. CLASS="sect1"
  38015. ><HR><H2
  38016. CLASS="sect1"
  38017. ><A
  38018. NAME="security.database.design"
  38019. >Designing Databases</A
  38020. ></H2
  38021. ><P
  38022. >       The first step is always to create the database, unless you want to use
  38023.       one from a third party. When a database is created, it is
  38024.       assigned to an owner, who executed the creation statement. Usually, only
  38025.       the owner (or a superuser) can do anything with the objects in that
  38026.       database, and in order to allow other users to use it, privileges must be
  38027.       granted.
  38028.      </P
  38029. ><P
  38030. >       Applications should never connect to the database as its owner or a
  38031.       superuser, because these users can execute any query at will, for
  38032.       example, modifying the schema (e.g. dropping tables) or deleting its
  38033.       entire content.
  38034.      </P
  38035. ><P
  38036. >       You may create different database users for every aspect of your
  38037.       application with very limited rights to database objects. The most
  38038.       required privileges should be granted only, and avoid that the same user
  38039.       can interact with the database in different use cases. This means that if
  38040.       intruders gain access to your database using your applications credentials,
  38041.       they can only effect as many changes as your application can.
  38042.      </P
  38043. ><P
  38044. >       You are encouraged not to implement all the business logic in the web
  38045.       application (i.e. your script), instead do it in the database schema
  38046.       using views, triggers or rules. If the system evolves, new ports will be
  38047.       intended to open to the database, and you have to re-implement the logic
  38048.       in each separate database client. Over and above, triggers can be used
  38049.       to transparently and automatically handle fields, which often provides
  38050.       insight when debugging problems with your application or tracing back
  38051.       transactions.
  38052.      </P
  38053. ></DIV
  38054. ><DIV
  38055. CLASS="sect1"
  38056. ><HR><H2
  38057. CLASS="sect1"
  38058. ><A
  38059. NAME="security.database.connection"
  38060. >Connecting to Database</A
  38061. ></H2
  38062. ><P
  38063. >      You may want to establish the connections over SSL to encrypt
  38064.      client/server communications for increased security, or you can use ssh
  38065.      to encrypt the network connection between clients and the database server.
  38066.      If either of these is used, then monitoring your traffic and gaining
  38067.      information about your database will be difficult for a would-be attacker.
  38068.     </P
  38069. ></DIV
  38070. ><DIV
  38071. CLASS="sect1"
  38072. ><HR><H2
  38073. CLASS="sect1"
  38074. ><A
  38075. NAME="security.database.storage"
  38076. >Encrypted Storage Model</A
  38077. ></H2
  38078. ><P
  38079. >      SSL/SSH protects data travelling from the client to the server, SSL/SSH
  38080.      does not protect the persistent data stored in a database. SSL is an
  38081.      on-the-wire protocol.
  38082.     </P
  38083. ><P
  38084. >      Once an attacker gains access to your database directly (bypassing the
  38085.      webserver), the stored sensitive data may be exposed or misused, unless
  38086.      the information is protected by the database itself. Encrypting the data
  38087.      is a good way to mitigate this threat, but very few databases offer this
  38088.      type of data encryption.
  38089.     </P
  38090. ><P
  38091. >      The easiest way to work around this problem is to first create your own
  38092.      encryption package, and then use it from within your PHP scripts. PHP
  38093.      can assist you in this with several extensions, such as <A
  38094. HREF="#ref.mcrypt"
  38095. >Mcrypt</A
  38096. > and <A
  38097. HREF="#ref.mhash"
  38098. >Mhash</A
  38099. >, covering a wide variety of encryption
  38100.      algorithms. The script encrypts the data before inserting it into the database, and decrypts
  38101.      it when retrieving. See the references for further examples of how
  38102.      encryption works.
  38103.     </P
  38104. ><P
  38105. >      In case of truly hidden data, if its raw representation is not needed
  38106.      (i.e. not be displayed), hashing may also be taken into consideration.
  38107.      The well-known example for the hashing is storing the MD5 hash of a
  38108.      password in a database, instead of the password itself. See also
  38109.      <A
  38110. HREF="#function.crypt"
  38111. ><B
  38112. CLASS="function"
  38113. >crypt()</B
  38114. ></A
  38115. > and <A
  38116. HREF="#function.md5"
  38117. ><B
  38118. CLASS="function"
  38119. >md5()</B
  38120. ></A
  38121. >.
  38122.     </P
  38123. ><TABLE
  38124. WIDTH="100%"
  38125. BORDER="0"
  38126. CELLPADDING="0"
  38127. CELLSPACING="0"
  38128. CLASS="EXAMPLE"
  38129. ><TR
  38130. ><TD
  38131. ><DIV
  38132. CLASS="example"
  38133. ><A
  38134. NAME="AEN6205"
  38135. ></A
  38136. ><P
  38137. ><B
  38138. >Example 27-1. Using hashed password field</B
  38139. ></P
  38140. ><TABLE
  38141. BORDER="0"
  38142. BGCOLOR="#E0E0E0"
  38143. CELLPADDING="5"
  38144. ><TR
  38145. ><TD
  38146. ><PRE
  38147. CLASS="php"
  38148. ><?php
  38149.  
  38150. // storing password hash
  38151. $query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
  38152.             addslashes($username), md5($password));
  38153. $result = pg_query($connection, $query);
  38154.  
  38155. // querying if user submitted the right password
  38156. $query = sprintf("SELECT 1 FROM users WHERE name='%s' AND pwd='%s';",
  38157.             addslashes($username), md5($password));
  38158. $result = pg_query($connection, $query);
  38159.  
  38160. if (pg_num_rows($result) > 0) {
  38161.     echo 'Welcome, $username!';
  38162. } else {
  38163.     echo 'Authentication failed for $username.';
  38164. }
  38165.  
  38166. ?></PRE
  38167. ></TD
  38168. ></TR
  38169. ></TABLE
  38170. ></DIV
  38171. ></TD
  38172. ></TR
  38173. ></TABLE
  38174. ></DIV
  38175. ><DIV
  38176. CLASS="sect1"
  38177. ><HR><H2
  38178. CLASS="sect1"
  38179. ><A
  38180. NAME="security.database.sql-injection"
  38181. >SQL Injection</A
  38182. ></H2
  38183. ><P
  38184. >      Many web developers are unaware of how SQL queries can be tampered with,
  38185.      and assume that an SQL query is a trusted command. It means that SQL
  38186.      queries are able to circumvent access controls, thereby bypassing standard
  38187.      authentication and authorization checks, and sometimes SQL queries even
  38188.      may allow access to host operating system level commands.
  38189.     </P
  38190. ><P
  38191. >      Direct SQL Command Injection is a technique where an attacker creates or
  38192.      alters existing SQL commands to expose hidden data, or to override valuable
  38193.      ones, or even to execute dangerous system level commands on the database
  38194.      host. This is accomplished by the application taking user input and
  38195.      combining it with static parameters to build a SQL query. The following
  38196.      examples are based on true stories, unfortunately.
  38197.     </P
  38198. ><P
  38199. >      Owing to the lack of input validation and connecting to the database on
  38200.      behalf of a superuser or the one who can create users, the attacker
  38201.      may create a superuser in your database.
  38202.      <TABLE
  38203. WIDTH="100%"
  38204. BORDER="0"
  38205. CELLPADDING="0"
  38206. CELLSPACING="0"
  38207. CLASS="EXAMPLE"
  38208. ><TR
  38209. ><TD
  38210. ><DIV
  38211. CLASS="example"
  38212. ><A
  38213. NAME="AEN6213"
  38214. ></A
  38215. ><P
  38216. ><B
  38217. >Example 27-2. 
  38218.        Splitting the result set into pages ... and making superusers
  38219.        (PostgreSQL and MySQL)
  38220.       </B
  38221. ></P
  38222. ><TABLE
  38223. BORDER="0"
  38224. BGCOLOR="#E0E0E0"
  38225. CELLPADDING="5"
  38226. ><TR
  38227. ><TD
  38228. ><PRE
  38229. CLASS="php"
  38230. ><?php
  38231.  
  38232. $offset = $argv[0]; // beware, no input validation!
  38233. $query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
  38234. // with PostgreSQL 
  38235. $result = pg_query($conn, $query);
  38236. // with MySQL
  38237. $result = mysql_query($query);
  38238.  
  38239. ?></PRE
  38240. ></TD
  38241. ></TR
  38242. ></TABLE
  38243. ></DIV
  38244. ></TD
  38245. ></TR
  38246. ></TABLE
  38247. >
  38248.       Normal users click on the 'next', 'prev' links where the <VAR
  38249. CLASS="varname"
  38250. >$offset</VAR
  38251. >
  38252.       is encoded into the URL. The script expects that the incoming
  38253.       <VAR
  38254. CLASS="varname"
  38255. >$offset</VAR
  38256. > is a decimal number. However, what if someone tries to
  38257.       break in by appending a <A
  38258. HREF="#function.urlencode"
  38259. ><B
  38260. CLASS="function"
  38261. >urlencode()</B
  38262. ></A
  38263. >'d form of the
  38264.       following to the URL
  38265.       <DIV
  38266. CLASS="informalexample"
  38267. ><P
  38268. ></P
  38269. ><A
  38270. NAME="AEN6219"
  38271. ></A
  38272. ><TABLE
  38273. BORDER="0"
  38274. BGCOLOR="#E0E0E0"
  38275. CELLPADDING="5"
  38276. ><TR
  38277. ><TD
  38278. ><PRE
  38279. CLASS="sql"
  38280. >// in case of PostgreSQL
  38281. 0;
  38282. insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
  38283.     select 'crack', usesysid, 't','t','crack'
  38284.     from pg_shadow where usename='postgres';
  38285. --
  38286.  
  38287. // in case of MySQL
  38288. 0;
  38289. UPDATE user SET Password=PASSWORD('crack') WHERE user='root';
  38290. FLUSH PRIVILEGES;</PRE
  38291. ></TD
  38292. ></TR
  38293. ></TABLE
  38294. ><P
  38295. ></P
  38296. ></DIV
  38297. >
  38298.       If it happened, then the script would present a superuser access to him.
  38299.       Note that <VAR
  38300. CLASS="literal"
  38301. >0;</VAR
  38302. > is to supply a valid offset to the
  38303.       original query and to terminate it.
  38304.     </P
  38305. ><DIV
  38306. CLASS="note"
  38307. ><BLOCKQUOTE
  38308. CLASS="note"
  38309. ><P
  38310. ><B
  38311. >Note: </B
  38312. >
  38313.       It is common technique to force the SQL parser to ignore the rest of the
  38314.       query written by the developer with <VAR
  38315. CLASS="literal"
  38316. >--</VAR
  38317. > which is the
  38318.       comment sign in SQL.
  38319.      </P
  38320. ></BLOCKQUOTE
  38321. ></DIV
  38322. ><P
  38323. >      A feasible way to gain passwords is to circumvent your search result pages.
  38324.      The only thing the attacker needs to do is to see if there are any submitted variables
  38325.      used in SQL statements which are not handled properly. These filters can be set
  38326.      commonly in a preceding form to customize <VAR
  38327. CLASS="literal"
  38328. >WHERE, ORDER BY,
  38329.      LIMIT</VAR
  38330. > and <VAR
  38331. CLASS="literal"
  38332. >OFFSET</VAR
  38333. > clauses in <VAR
  38334. CLASS="literal"
  38335. >SELECT</VAR
  38336. >
  38337.      statements. If your database supports the <VAR
  38338. CLASS="literal"
  38339. >UNION</VAR
  38340. > construct,
  38341.      the attacker may try to append an entire query to the original one to list
  38342.      passwords from an arbitrary table. Using encrypted password fields is 
  38343.      strongly encouraged.
  38344.      <TABLE
  38345. WIDTH="100%"
  38346. BORDER="0"
  38347. CELLPADDING="0"
  38348. CELLSPACING="0"
  38349. CLASS="EXAMPLE"
  38350. ><TR
  38351. ><TD
  38352. ><DIV
  38353. CLASS="example"
  38354. ><A
  38355. NAME="AEN6230"
  38356. ></A
  38357. ><P
  38358. ><B
  38359. >Example 27-3. 
  38360.        Listing out articles ... and some passwords (any database server)
  38361.       </B
  38362. ></P
  38363. ><TABLE
  38364. BORDER="0"
  38365. BGCOLOR="#E0E0E0"
  38366. CELLPADDING="5"
  38367. ><TR
  38368. ><TD
  38369. ><PRE
  38370. CLASS="php"
  38371. ><?php
  38372.  
  38373. $query  = "SELECT id, name, inserted, size FROM products
  38374.                   WHERE size = '$size'
  38375.                   ORDER BY $order LIMIT $limit, $offset;";
  38376. $result = odbc_exec($conn, $query);
  38377.  
  38378. ?></PRE
  38379. ></TD
  38380. ></TR
  38381. ></TABLE
  38382. ></DIV
  38383. ></TD
  38384. ></TR
  38385. ></TABLE
  38386. >
  38387.      The static part of the query can be combined with another
  38388.      <VAR
  38389. CLASS="literal"
  38390. >SELECT</VAR
  38391. > statement which reveals all passwords:
  38392.      <DIV
  38393. CLASS="informalexample"
  38394. ><P
  38395. ></P
  38396. ><A
  38397. NAME="AEN6234"
  38398. ></A
  38399. ><TABLE
  38400. BORDER="0"
  38401. BGCOLOR="#E0E0E0"
  38402. CELLPADDING="5"
  38403. ><TR
  38404. ><TD
  38405. ><PRE
  38406. CLASS="sql"
  38407. >'
  38408. union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
  38409. --</PRE
  38410. ></TD
  38411. ></TR
  38412. ></TABLE
  38413. ><P
  38414. ></P
  38415. ></DIV
  38416. >
  38417.      If this query (playing with the <VAR
  38418. CLASS="literal"
  38419. >'</VAR
  38420. > and
  38421.      <VAR
  38422. CLASS="literal"
  38423. >--</VAR
  38424. >) were assigned to one of the variables used in
  38425.      <VAR
  38426. CLASS="varname"
  38427. >$query</VAR
  38428. >, the query beast awakened.
  38429.     </P
  38430. ><P
  38431. >      SQL UPDATE's are also susceptible to attack. These queries are
  38432.      also threatened by chopping and appending an entirely new query to it. But
  38433.      the attacker might fiddle with the <VAR
  38434. CLASS="literal"
  38435. >SET</VAR
  38436. > clause. In this
  38437.      case some schema information must be possessed to manipulate the query
  38438.      successfully. This can be acquired by examining the form variable names, or
  38439.      just simply brute forcing. There are not so many naming conventions for
  38440.      fields storing passwords or usernames.
  38441.      <TABLE
  38442. WIDTH="100%"
  38443. BORDER="0"
  38444. CELLPADDING="0"
  38445. CELLSPACING="0"
  38446. CLASS="EXAMPLE"
  38447. ><TR
  38448. ><TD
  38449. ><DIV
  38450. CLASS="example"
  38451. ><A
  38452. NAME="AEN6241"
  38453. ></A
  38454. ><P
  38455. ><B
  38456. >Example 27-4. 
  38457.       From resetting a password ... to gaining more privileges (any database server)
  38458.      </B
  38459. ></P
  38460. ><TABLE
  38461. BORDER="0"
  38462. BGCOLOR="#E0E0E0"
  38463. CELLPADDING="5"
  38464. ><TR
  38465. ><TD
  38466. ><PRE
  38467. CLASS="php"
  38468. ><?php
  38469. $query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
  38470. ?></PRE
  38471. ></TD
  38472. ></TR
  38473. ></TABLE
  38474. ></DIV
  38475. ></TD
  38476. ></TR
  38477. ></TABLE
  38478. >
  38479.      But a malicious user sumbits the value
  38480.      <VAR
  38481. CLASS="literal"
  38482. >' or uid like'%admin%'; --</VAR
  38483. > to <VAR
  38484. CLASS="varname"
  38485. >$uid</VAR
  38486. > to
  38487.      change the admin's password, or simply sets <VAR
  38488. CLASS="varname"
  38489. >$pwd</VAR
  38490. > to
  38491.      <VAR
  38492. CLASS="literal"
  38493. >"hehehe', admin='yes', trusted=100 "</VAR
  38494. > (with a trailing
  38495.      space) to gain more privileges. Then, the query will be twisted:
  38496.      <DIV
  38497. CLASS="informalexample"
  38498. ><P
  38499. ></P
  38500. ><A
  38501. NAME="AEN6248"
  38502. ></A
  38503. ><TABLE
  38504. BORDER="0"
  38505. BGCOLOR="#E0E0E0"
  38506. CELLPADDING="5"
  38507. ><TR
  38508. ><TD
  38509. ><PRE
  38510. CLASS="php"
  38511. ><?php
  38512.  
  38513. // $uid == ' or uid like'%admin%'; --
  38514. $query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%'; --";
  38515.  
  38516. // $pwd == "hehehe', admin='yes', trusted=100 "
  38517. $query = "UPDATE usertable SET pwd='hehehe', admin='yes', trusted=100 WHERE
  38518. ...;";
  38519.  
  38520. ?></PRE
  38521. ></TD
  38522. ></TR
  38523. ></TABLE
  38524. ><P
  38525. ></P
  38526. ></DIV
  38527. >
  38528.     </P
  38529. ><P
  38530. >      A frightening example how operating system level commands can be accessed
  38531.      on some database hosts.
  38532.      <TABLE
  38533. WIDTH="100%"
  38534. BORDER="0"
  38535. CELLPADDING="0"
  38536. CELLSPACING="0"
  38537. CLASS="EXAMPLE"
  38538. ><TR
  38539. ><TD
  38540. ><DIV
  38541. CLASS="example"
  38542. ><A
  38543. NAME="AEN6251"
  38544. ></A
  38545. ><P
  38546. ><B
  38547. >Example 27-5. Attacking the database hosts operating system (MSSQL Server)</B
  38548. ></P
  38549. ><TABLE
  38550. BORDER="0"
  38551. BGCOLOR="#E0E0E0"
  38552. CELLPADDING="5"
  38553. ><TR
  38554. ><TD
  38555. ><PRE
  38556. CLASS="php"
  38557. ><?php
  38558.  
  38559. $query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
  38560. $result = mssql_query($query);
  38561.  
  38562. ?></PRE
  38563. ></TD
  38564. ></TR
  38565. ></TABLE
  38566. ></DIV
  38567. ></TD
  38568. ></TR
  38569. ></TABLE
  38570. >
  38571.      If attacker submits the value
  38572.      <VAR
  38573. CLASS="literal"
  38574. >a%' exec master..xp_cmdshell 'net user test testpass /ADD' --</VAR
  38575. >
  38576.      to <VAR
  38577. CLASS="varname"
  38578. >$prod</VAR
  38579. >, then the <VAR
  38580. CLASS="varname"
  38581. >$query</VAR
  38582. > will be:
  38583.      <DIV
  38584. CLASS="informalexample"
  38585. ><P
  38586. ></P
  38587. ><A
  38588. NAME="AEN6257"
  38589. ></A
  38590. ><TABLE
  38591. BORDER="0"
  38592. BGCOLOR="#E0E0E0"
  38593. CELLPADDING="5"
  38594. ><TR
  38595. ><TD
  38596. ><PRE
  38597. CLASS="php"
  38598. ><?php
  38599.  
  38600. $query  = "SELECT * FROM products
  38601.                     WHERE id LIKE '%a%'
  38602.                     exec master..xp_cmdshell 'net user test testpass /ADD'--";
  38603. $result = mssql_query($query);
  38604.  
  38605. ?></PRE
  38606. ></TD
  38607. ></TR
  38608. ></TABLE
  38609. ><P
  38610. ></P
  38611. ></DIV
  38612. >
  38613.      MSSQL Server executes the SQL statements in the batch including a command
  38614.      to add a new user to the local accounts database. If this application
  38615.      were running as <VAR
  38616. CLASS="literal"
  38617. >sa</VAR
  38618. > and the MSSQLSERVER service is
  38619.      running with sufficient privileges, the attacker would now have an
  38620.      account with which to access this machine.
  38621.     </P
  38622. ><DIV
  38623. CLASS="note"
  38624. ><BLOCKQUOTE
  38625. CLASS="note"
  38626. ><P
  38627. ><B
  38628. >Note: </B
  38629. >
  38630.       Some of the examples above is tied to a specific database server. This
  38631.       does not mean that a similar attack is impossible against other products.
  38632.       Your database server may be similarly vulnerable in another manner.
  38633.      </P
  38634. ></BLOCKQUOTE
  38635. ></DIV
  38636. ><DIV
  38637. CLASS="sect2"
  38638. ><HR><H3
  38639. CLASS="sect2"
  38640. ><A
  38641. NAME="security.database.avoiding"
  38642. >Avoiding techniques</A
  38643. ></H3
  38644. ><P
  38645. >       You may plead that the attacker must possess a piece of information
  38646.       about the database schema in most examples. You are right, but you
  38647.       never know when and how it can be taken out, and if it happens,
  38648.       your database may be exposed. If you are using an open source, or
  38649.       publicly available database handling package, which may belong to a
  38650.       content management system or forum, the intruders easily produce
  38651.       a copy of a piece of your code. It may be also a security risk if it
  38652.       is a poorly designed one.
  38653.      </P
  38654. ><P
  38655. >       These attacks are mainly based on exploiting the code not being written
  38656.       with security in mind. Never trust any kind of input, especially that
  38657.       which comes from the client side, even though it comes from a select box,
  38658.       a hidden input field or a cookie. The first example shows that such a
  38659.       blameless query can cause disasters.
  38660.      </P
  38661. ><P
  38662. ></P
  38663. ><UL
  38664. ><LI
  38665. ><P
  38666. >         Never connect to the database as a superuser or as the database owner.
  38667.         Use always customized users with very limited privileges.
  38668.        </P
  38669. ></LI
  38670. ><LI
  38671. ><P
  38672. >         Check if the given input has the expected data type. PHP has
  38673.         a wide range of input validating functions, from the simplest ones
  38674.         found in <A
  38675. HREF="#ref.var"
  38676. >Variable Functions</A
  38677. > and
  38678.         in <A
  38679. HREF="#ref.ctype"
  38680. >Character Type Functions</A
  38681. >
  38682.         (e.g. <A
  38683. HREF="#function.is-numeric"
  38684. ><B
  38685. CLASS="function"
  38686. >is_numeric()</B
  38687. ></A
  38688. >, <A
  38689. HREF="#function.ctype-digit"
  38690. ><B
  38691. CLASS="function"
  38692. >ctype_digit()</B
  38693. ></A
  38694. >
  38695.         respectively) and onwards to the
  38696.         <A
  38697. HREF="#ref.pcre"
  38698. >Perl compatible Regular Expressions</A
  38699. >
  38700.         support.
  38701.        </P
  38702. ></LI
  38703. ><LI
  38704. ><P
  38705. >         If the application waits for numerical input, consider verifying data
  38706.         with <A
  38707. HREF="#function.is-numeric"
  38708. ><B
  38709. CLASS="function"
  38710. >is_numeric()</B
  38711. ></A
  38712. >, or silently change its type
  38713.         using <A
  38714. HREF="#function.settype"
  38715. ><B
  38716. CLASS="function"
  38717. >settype()</B
  38718. ></A
  38719. >, or use its numeric representation
  38720.         by <A
  38721. HREF="#function.sprintf"
  38722. ><B
  38723. CLASS="function"
  38724. >sprintf()</B
  38725. ></A
  38726. >.
  38727.         <TABLE
  38728. WIDTH="100%"
  38729. BORDER="0"
  38730. CELLPADDING="0"
  38731. CELLSPACING="0"
  38732. CLASS="EXAMPLE"
  38733. ><TR
  38734. ><TD
  38735. ><DIV
  38736. CLASS="example"
  38737. ><A
  38738. NAME="AEN6281"
  38739. ></A
  38740. ><P
  38741. ><B
  38742. >Example 27-6. A more secure way to compose a query for paging</B
  38743. ></P
  38744. ><TABLE
  38745. BORDER="0"
  38746. BGCOLOR="#E0E0E0"
  38747. CELLPADDING="5"
  38748. ><TR
  38749. ><TD
  38750. ><PRE
  38751. CLASS="php"
  38752. ><?php
  38753.  
  38754. settype($offset, 'integer');
  38755. $query = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
  38756.  
  38757. // please note %d in the format string, using %s would be meaningless
  38758. $query = sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;",
  38759.                  $offset);
  38760.  
  38761. ?></PRE
  38762. ></TD
  38763. ></TR
  38764. ></TABLE
  38765. ></DIV
  38766. ></TD
  38767. ></TR
  38768. ></TABLE
  38769. >
  38770.        </P
  38771. ></LI
  38772. ><LI
  38773. ><P
  38774. >         Quote each non numeric user supplied value that is passed to the
  38775.         database with the database-specific string escape function (e.g.
  38776.         <A
  38777. HREF="#function.mysql-escape-string"
  38778. ><B
  38779. CLASS="function"
  38780. >mysql_escape_string()</B
  38781. ></A
  38782. >,
  38783.         <B
  38784. CLASS="function"
  38785. >sql_escape_string()</B
  38786. >, etc.). If a database-specific
  38787.         string escape mechanism is not available, the
  38788.         <A
  38789. HREF="#function.addslashes"
  38790. ><B
  38791. CLASS="function"
  38792. >addslashes()</B
  38793. ></A
  38794. > and <A
  38795. HREF="#function.str-replace"
  38796. ><B
  38797. CLASS="function"
  38798. >str_replace()</B
  38799. ></A
  38800. >
  38801.         functions may be useful (depending on database type).
  38802.         See <A
  38803. HREF="#security.database.storage"
  38804. >the first example</A
  38805. >.
  38806.         As the example shows, adding quotes to the static part of the query
  38807.         is not enough, making this query easily crackable.
  38808.        </P
  38809. ></LI
  38810. ><LI
  38811. ><P
  38812. >         Do not print out any database specific information, especially
  38813.         about the schema, by fair means or foul. See also <A
  38814. HREF="#security.errors"
  38815. >Error Reporting</A
  38816. > and <A
  38817. HREF="#ref.errorfunc"
  38818. >Error Handling and Logging Functions</A
  38819. >.
  38820.        </P
  38821. ></LI
  38822. ><LI
  38823. ><P
  38824. >         You may use stored procedures and previously defined cursors to abstract
  38825.         data access so that users do not directly access tables or views, but
  38826.         this solution has another impacts.
  38827.        </P
  38828. ></LI
  38829. ></UL
  38830. ><P
  38831. >       Besides these, you benefit from logging queries either within your script
  38832.       or by the database itself, if it supports logging. Obviously, the logging is unable
  38833.       to prevent any harmful attempt, but it can be helpful to trace back which
  38834.       application has been circumvented. The log is not useful by itself, but
  38835.       through the information it contains. More detail is generally better than less.
  38836.      </P
  38837. ></DIV
  38838. ></DIV
  38839. ></DIV
  38840. ><DIV
  38841. CLASS="chapter"
  38842. ><HR><H1
  38843. ><A
  38844. NAME="security.errors"
  38845. >Chapter 28. Error Reporting</A
  38846. ></H1
  38847. ><P
  38848. >     With PHP security, there are two sides to error reporting. One is
  38849.     beneficial to increasing security, the other is detrimental.
  38850.    </P
  38851. ><P
  38852. >     A standard attack tactic involves profiling a system by feeding
  38853.     it improper data, and checking for the kinds, and contexts, of the
  38854.     errors which are returned. This allows the system cracker to probe
  38855.     for information about the server, to determine possible weaknesses.
  38856.     For example, if an attacker had gleaned information about a page
  38857.     based on a prior form submission, they may attempt to override
  38858.     variables, or modify them:
  38859.     <TABLE
  38860. WIDTH="100%"
  38861. BORDER="0"
  38862. CELLPADDING="0"
  38863. CELLSPACING="0"
  38864. CLASS="EXAMPLE"
  38865. ><TR
  38866. ><TD
  38867. ><DIV
  38868. CLASS="example"
  38869. ><A
  38870. NAME="AEN6302"
  38871. ></A
  38872. ><P
  38873. ><B
  38874. >Example 28-1. Attacking Variables with a custom HTML page</B
  38875. ></P
  38876. ><TABLE
  38877. BORDER="0"
  38878. BGCOLOR="#E0E0E0"
  38879. CELLPADDING="5"
  38880. ><TR
  38881. ><TD
  38882. ><PRE
  38883. CLASS="html"
  38884. ><form method="post" action="attacktarget?username=badfoo&amp;password=badfoo">
  38885. <input type="hidden" name="username" value="badfoo" />
  38886. <input type="hidden" name="password" value="badfoo" />
  38887. </form></PRE
  38888. ></TD
  38889. ></TR
  38890. ></TABLE
  38891. ></DIV
  38892. ></TD
  38893. ></TR
  38894. ></TABLE
  38895. >
  38896.    </P
  38897. ><P
  38898. >     The PHP errors which are normally returned can be quite helpful to a
  38899.     developer who is trying to debug a script, indicating such things
  38900.     as the function or file that failed, the PHP file it failed in,
  38901.     and the line number which the failure occurred in. This is all
  38902.     information that can be exploited.  It is not uncommon for a php
  38903.     developer to use <A
  38904. HREF="#function.show-source"
  38905. ><B
  38906. CLASS="function"
  38907. >show_source()</B
  38908. ></A
  38909. >,
  38910.     <A
  38911. HREF="#function.highlight-string"
  38912. ><B
  38913. CLASS="function"
  38914. >highlight_string()</B
  38915. ></A
  38916. >, or
  38917.     <A
  38918. HREF="#function.highlight-file"
  38919. ><B
  38920. CLASS="function"
  38921. >highlight_file()</B
  38922. ></A
  38923. > as a debugging measure, but in
  38924.     a live site, this can expose hidden variables, unchecked syntax,
  38925.     and other dangerous information. Especially dangerous is running
  38926.     code from known sources with built-in debugging handlers, or using
  38927.     common debugging techniques. If the attacker can determine what
  38928.     general technique you are using, they may try to brute-force a page,
  38929.     by sending various common debugging strings:
  38930.     <TABLE
  38931. WIDTH="100%"
  38932. BORDER="0"
  38933. CELLPADDING="0"
  38934. CELLSPACING="0"
  38935. CLASS="EXAMPLE"
  38936. ><TR
  38937. ><TD
  38938. ><DIV
  38939. CLASS="example"
  38940. ><A
  38941. NAME="AEN6309"
  38942. ></A
  38943. ><P
  38944. ><B
  38945. >Example 28-2. Exploiting common debugging variables</B
  38946. ></P
  38947. ><TABLE
  38948. BORDER="0"
  38949. BGCOLOR="#E0E0E0"
  38950. CELLPADDING="5"
  38951. ><TR
  38952. ><TD
  38953. ><PRE
  38954. CLASS="html"
  38955. ><form method="post" action="attacktarget?errors=Y&amp;showerrors=1&amp;debug=1">
  38956. <input type="hidden" name="errors" value="Y" />
  38957. <input type="hidden" name="showerrors" value="1" />
  38958. <input type="hidden" name="debug" value="1" />
  38959. </form></PRE
  38960. ></TD
  38961. ></TR
  38962. ></TABLE
  38963. ></DIV
  38964. ></TD
  38965. ></TR
  38966. ></TABLE
  38967. >
  38968.    </P
  38969. ><P
  38970. >     Regardless of the method of error handling, the ability to probe a
  38971.     system for errors leads to providing an attacker with more
  38972.     information.
  38973.    </P
  38974. ><P
  38975. >     For example, the very style of a generic PHP error indicates a system
  38976.     is running PHP. If the attacker was looking at an .html page, and
  38977.     wanted to probe for the back-end (to look for known weaknesses in
  38978.     the system), by feeding it the wrong data they may be able to
  38979.     determine that a system was built with PHP.
  38980.    </P
  38981. ><P
  38982. >     A function error can indicate whether a system may be running a
  38983.     specific database engine, or give clues as to how a web page or
  38984.     programmed or designed. This allows for deeper investigation into
  38985.     open database ports, or to look for specific bugs or weaknesses
  38986.     in a web page. By feeding different pieces of bad data, for example,
  38987.     an attacker can determine the order of authentication in a script,
  38988.     (from the line number errors) as well as probe for exploits that
  38989.     may be exploited in different locations in the script.
  38990.    </P
  38991. ><P
  38992. >     A filesystem or general PHP error can indicate what permissions
  38993.     the webserver has, as well as the structure and organization of
  38994.     files on the web server. Developer written error code can aggravate
  38995.     this problem, leading to easy exploitation of formerly "hidden"
  38996.     information.
  38997.    </P
  38998. ><P
  38999. >     There are three major solutions to this issue. The first is to
  39000.     scrutinize all functions, and attempt to compensate for the bulk
  39001.     of the errors. The second is to disable error reporting entirely
  39002.     on the running code. The third is to use PHP's custom error
  39003.     handling functions to create your own error handler. Depending
  39004.     on your security policy, you may find all three to be applicable
  39005.     to your situation.
  39006.    </P
  39007. ><P
  39008. >     One way of catching this issue ahead of time is to make use of
  39009.     PHP's own <A
  39010. HREF="#function.error-reporting"
  39011. ><B
  39012. CLASS="function"
  39013. >error_reporting()</B
  39014. ></A
  39015. >, to help you
  39016.     secure your code and find variable usage that may be dangerous.
  39017.     By testing your code, prior to deployment, with E_ALL, you can
  39018.     quickly find areas where your variables may be open to poisoning
  39019.     or modification in other ways. Once you are ready for deployment,
  39020.     by using E_NONE, you insulate your code from probing.
  39021.     <TABLE
  39022. WIDTH="100%"
  39023. BORDER="0"
  39024. CELLPADDING="0"
  39025. CELLSPACING="0"
  39026. CLASS="EXAMPLE"
  39027. ><TR
  39028. ><TD
  39029. ><DIV
  39030. CLASS="example"
  39031. ><A
  39032. NAME="AEN6319"
  39033. ></A
  39034. ><P
  39035. ><B
  39036. >Example 28-3. Finding dangerous variables with E_ALL</B
  39037. ></P
  39038. ><TABLE
  39039. BORDER="0"
  39040. BGCOLOR="#E0E0E0"
  39041. CELLPADDING="5"
  39042. ><TR
  39043. ><TD
  39044. ><PRE
  39045. CLASS="php"
  39046. ><?php
  39047. if ($username) {  // Not initialized or checked before usage
  39048.     $good_login = 1;
  39049. }
  39050. if ($good_login == 1) { // If above test fails, not initialized or checked before usage
  39051.     readfile ("/highly/sensitive/data/index.html");
  39052. }
  39053. ?></PRE
  39054. ></TD
  39055. ></TR
  39056. ></TABLE
  39057. ></DIV
  39058. ></TD
  39059. ></TR
  39060. ></TABLE
  39061. >
  39062.    </P
  39063. ></DIV
  39064. ><DIV
  39065. CLASS="chapter"
  39066. ><HR><H1
  39067. ><A
  39068. NAME="security.globals"
  39069. >Chapter 29. Using Register Globals</A
  39070. ></H1
  39071. ><P
  39072. >     Perhaps the most controversial change in PHP is when the default value
  39073.     for the PHP directive <A
  39074. HREF="#ini.register-globals"
  39075. >     register_globals</A
  39076. > went from ON to OFF in PHP 
  39077.     <A
  39078. HREF="http://www.php.net/release_4_2_0.php"
  39079. TARGET="_top"
  39080. >4.2.0</A
  39081. >.  Reliance on this
  39082.     directive was quite common and many people didn't even know it existed
  39083.     and assumed it's just how PHP works.  This page will explain how one can
  39084.     write insecure code with this directive but keep in mind that the
  39085.     directive itself isn't insecure but rather it's the misuse of it.
  39086.    </P
  39087. ><P
  39088. >     When on, register_globals will inject (poison) your scripts will all
  39089.     sorts of variables, like request variables from HTML forms.  This
  39090.     coupled with the fact that PHP doesn't require variable initialization
  39091.     means writing insecure code is that much easier.  It was a difficult
  39092.     decision, but the PHP community decided to disable this directive by 
  39093.     default.  When on, people use variables yet really don't know for sure
  39094.     where they come from and can only assume.  Internal variables that are
  39095.     defined in the script itself get mixed up with request data sent by
  39096.     users and disabling register_globals changes this.  Let's demonstrate
  39097.     with an example misuse of register_globals: 
  39098.    </P
  39099. ><P
  39100. >     <TABLE
  39101. WIDTH="100%"
  39102. BORDER="0"
  39103. CELLPADDING="0"
  39104. CELLSPACING="0"
  39105. CLASS="EXAMPLE"
  39106. ><TR
  39107. ><TD
  39108. ><DIV
  39109. CLASS="example"
  39110. ><A
  39111. NAME="AEN6329"
  39112. ></A
  39113. ><P
  39114. ><B
  39115. >Example 29-1. Example misuse with register_globals = on</B
  39116. ></P
  39117. ><TABLE
  39118. BORDER="0"
  39119. BGCOLOR="#E0E0E0"
  39120. CELLPADDING="5"
  39121. ><TR
  39122. ><TD
  39123. ><PRE
  39124. CLASS="php"
  39125. ><?php
  39126. // define $authorized = true only if user is authenticated
  39127. if (authenticated_user()) {
  39128.     $authorized = true;
  39129. }
  39130.  
  39131. // Because we didn't first initialize $authorized as false, this might be
  39132. // defined through register_globals, like from GET auth.php?authorized=1
  39133. // So, anyone can be seen as authenticated!
  39134. if ($authorized) {
  39135.     include "/highly/sensitive/data.php";
  39136. }
  39137. ?></PRE
  39138. ></TD
  39139. ></TR
  39140. ></TABLE
  39141. ></DIV
  39142. ></TD
  39143. ></TR
  39144. ></TABLE
  39145. >
  39146.    </P
  39147. ><P
  39148. >     When register_globals = on, our logic above may be compromised.  When
  39149.     off, <VAR
  39150. CLASS="varname"
  39151. >$authorized</VAR
  39152. > can't be set via request so it'll
  39153.     be fine, although it really is generally a good programming practice to
  39154.     initialize variables first.  For example, in our example above we might
  39155.     have first done <VAR
  39156. CLASS="literal"
  39157. >$authorized = false</VAR
  39158. >.  Doing this
  39159.     first means our above code would work with register_globals on or off as
  39160.     users by default would be unauthorized.
  39161.    </P
  39162. ><P
  39163. >     Another example is that of <A
  39164. HREF="#ref.session"
  39165. >sessions</A
  39166. >.
  39167.     When register_globals = on, we could also use
  39168.     <VAR
  39169. CLASS="varname"
  39170. >$username</VAR
  39171. > in our example below but again you must
  39172.     realize that <VAR
  39173. CLASS="varname"
  39174. >$username</VAR
  39175. > could also come from other
  39176.     means, such as GET (through the URL).
  39177.    </P
  39178. ><P
  39179. >     <TABLE
  39180. WIDTH="100%"
  39181. BORDER="0"
  39182. CELLPADDING="0"
  39183. CELLSPACING="0"
  39184. CLASS="EXAMPLE"
  39185. ><TR
  39186. ><TD
  39187. ><DIV
  39188. CLASS="example"
  39189. ><A
  39190. NAME="AEN6340"
  39191. ></A
  39192. ><P
  39193. ><B
  39194. >Example 29-2. Example use of sessions with register_globals on or off</B
  39195. ></P
  39196. ><TABLE
  39197. BORDER="0"
  39198. BGCOLOR="#E0E0E0"
  39199. CELLPADDING="5"
  39200. ><TR
  39201. ><TD
  39202. ><PRE
  39203. CLASS="php"
  39204. ><?php
  39205. // We wouldn't know where $username came from but do know $_SESSION is
  39206. // for session data
  39207. if (isset($_SESSION['username'])) {
  39208.  
  39209.     echo "Hello <b>{$_SESSION['username']}</b>";
  39210.  
  39211. } else {
  39212.  
  39213.     echo "Hello <b>Guest</b><br />";
  39214.     echo "Would you like to login?";
  39215.  
  39216. }
  39217. ?></PRE
  39218. ></TD
  39219. ></TR
  39220. ></TABLE
  39221. ></DIV
  39222. ></TD
  39223. ></TR
  39224. ></TABLE
  39225. >
  39226.    </P
  39227. ><P
  39228. >     It's even possible to take preventative measures to warn when forging is
  39229.     being attempted. If you know ahead of time exactly where a variable
  39230.     should be coming from, you can check to see if the submitted data is
  39231.     coming from an inappropriate kind of submission.  While it doesn't
  39232.     guarantee that data has not been forged, it does require an attacker to
  39233.     guess the right kind of forging.  If you don't care where the request
  39234.     data comes from, you can use <VAR
  39235. CLASS="varname"
  39236. >$_REQUEST</VAR
  39237. > as it contains
  39238.     a mix of GET, POST and COOKIE data.  See also the manual section on
  39239.     using <A
  39240. HREF="#language.variables.external"
  39241. >variables from outside
  39242.     of PHP</A
  39243. >.
  39244.    </P
  39245. ><P
  39246. >     <TABLE
  39247. WIDTH="100%"
  39248. BORDER="0"
  39249. CELLPADDING="0"
  39250. CELLSPACING="0"
  39251. CLASS="EXAMPLE"
  39252. ><TR
  39253. ><TD
  39254. ><DIV
  39255. CLASS="example"
  39256. ><A
  39257. NAME="AEN6347"
  39258. ></A
  39259. ><P
  39260. ><B
  39261. >Example 29-3. Detecting simple variable poisoning</B
  39262. ></P
  39263. ><TABLE
  39264. BORDER="0"
  39265. BGCOLOR="#E0E0E0"
  39266. CELLPADDING="5"
  39267. ><TR
  39268. ><TD
  39269. ><PRE
  39270. CLASS="php"
  39271. ><?php
  39272. if (isset($_COOKIE['MAGIC_COOKIE'])) {
  39273.  
  39274.     // MAGIC_COOKIE comes from a cookie.
  39275.     // Be sure to validate the cookie data!
  39276.  
  39277. } elseif (isset($_GET['MAGIC_COOKIE']) || isset($_POST['MAGIC_COOKIE'])) {
  39278.  
  39279.    mail("admin@example.com", "Possible breakin attempt", $_SERVER['REMOTE_ADDR']);
  39280.    echo "Security violation, admin has been alerted.";
  39281.    exit;
  39282.  
  39283. } else {
  39284.  
  39285.    // MAGIC_COOKIE isn't set through this REQUEST
  39286.  
  39287. }
  39288. ?></PRE
  39289. ></TD
  39290. ></TR
  39291. ></TABLE
  39292. ></DIV
  39293. ></TD
  39294. ></TR
  39295. ></TABLE
  39296. >
  39297.    </P
  39298. ><P
  39299. >     Of course, simply turning off register_globals does not mean your code
  39300.     is secure.  For every piece of data that is submitted, it should also be
  39301.     checked in other ways.  Always validate your user data and initialize
  39302.     your variables!  To check for uninitialized variables you may turn up
  39303.     <A
  39304. HREF="#function.error-reporting"
  39305. ><B
  39306. CLASS="function"
  39307. >error_reporting()</B
  39308. ></A
  39309. > to show
  39310.     <TT
  39311. CLASS="constant"
  39312. ><B
  39313. >E_NOTICE</B
  39314. ></TT
  39315. > level errors.
  39316.    </P
  39317. ><P
  39318. >     For information about emulating register_globals being On or Off, see this <A
  39319. HREF="#faq.misc.registerglobals"
  39320. >FAQ</A
  39321. >.
  39322.    </P
  39323. ><DIV
  39324. CLASS="note"
  39325. ><BLOCKQUOTE
  39326. CLASS="note"
  39327. ><P
  39328. ><B
  39329. >Superglobals: availability note: </B
  39330. >Since PHP 4.1.0, superglobal arrays such as <VAR
  39331. CLASS="varname"
  39332. >$_GET
  39333. </VAR
  39334. >, <VAR
  39335. CLASS="varname"
  39336. >$_POST</VAR
  39337. >, and <VAR
  39338. CLASS="varname"
  39339. >$_SERVER</VAR
  39340. >, 
  39341. etc. have  been available.  For more information, read the manual section 
  39342. on <A
  39343. HREF="#language.variables.predefined"
  39344. >superglobals</A
  39345. ></P
  39346. ></BLOCKQUOTE
  39347. ></DIV
  39348. ></DIV
  39349. ><DIV
  39350. CLASS="chapter"
  39351. ><HR><H1
  39352. ><A
  39353. NAME="security.variables"
  39354. >Chapter 30. User Submitted Data</A
  39355. ></H1
  39356. ><P
  39357. >     The greatest weakness in many PHP programs is not inherent in the
  39358.     language itself, but merely an issue of code not being written with
  39359.     security in mind. For this reason, you should always take the time
  39360.     to consider the implications of a given piece of code, to ascertain
  39361.     the possible damage if an unexpected variable is submitted to it.
  39362.     <TABLE
  39363. WIDTH="100%"
  39364. BORDER="0"
  39365. CELLPADDING="0"
  39366. CELLSPACING="0"
  39367. CLASS="EXAMPLE"
  39368. ><TR
  39369. ><TD
  39370. ><DIV
  39371. CLASS="example"
  39372. ><A
  39373. NAME="AEN6365"
  39374. ></A
  39375. ><P
  39376. ><B
  39377. >Example 30-1. Dangerous Variable Usage</B
  39378. ></P
  39379. ><TABLE
  39380. BORDER="0"
  39381. BGCOLOR="#E0E0E0"
  39382. CELLPADDING="5"
  39383. ><TR
  39384. ><TD
  39385. ><PRE
  39386. CLASS="php"
  39387. ><?php
  39388. // remove a file from the user's home directory... or maybe
  39389. // somebody else's?
  39390. unlink ($evil_var);
  39391.  
  39392. // Write logging of their access... or maybe an /etc/passwd entry?
  39393. fwrite ($fp, $evil_var);
  39394.  
  39395. // Execute something trivial.. or rm -rf *?
  39396. system ($evil_var);
  39397. exec ($evil_var);
  39398.  
  39399. ?></PRE
  39400. ></TD
  39401. ></TR
  39402. ></TABLE
  39403. ></DIV
  39404. ></TD
  39405. ></TR
  39406. ></TABLE
  39407. >
  39408.     You should always carefully examine your code to make sure that any
  39409.     variables being submitted from a web browser are being properly
  39410.     checked, and ask yourself the following questions:
  39411.     <P
  39412. ></P
  39413. ><UL
  39414. ><LI
  39415. ><P
  39416. >        Will this script only affect the intended files?
  39417.       </P
  39418. ></LI
  39419. ><LI
  39420. ><P
  39421. >        Can unusual or undesirable data be acted upon?
  39422.       </P
  39423. ></LI
  39424. ><LI
  39425. ><P
  39426. >        Can this script be used in unintended ways?
  39427.       </P
  39428. ></LI
  39429. ><LI
  39430. ><P
  39431. >        Can this be used in conjunction with other scripts in a negative
  39432.        manner?
  39433.       </P
  39434. ></LI
  39435. ><LI
  39436. ><P
  39437. >        Will any transactions be adequately logged?
  39438.       </P
  39439. ></LI
  39440. ></UL
  39441. >
  39442.     By adequately asking these questions while writing the script,
  39443.     rather than later, you prevent an unfortunate re-write when you
  39444.     need to increase your security. By starting out with this mindset,
  39445.     you won't guarantee the security of your system, but you can help
  39446.     improve it.
  39447.    </P
  39448. ><P
  39449. >     You may also want to consider turning off register_globals,
  39450.     magic_quotes, or other convenience settings which may confuse
  39451.     you as to the validity, source, or value of a given variable.
  39452.     Working with PHP in error_reporting(E_ALL) mode can also help warn
  39453.     you about variables being used before they are checked or
  39454.     initialized (so you can prevent unusual data from being
  39455.     operated upon).
  39456.    </P
  39457. ></DIV
  39458. ><DIV
  39459. CLASS="chapter"
  39460. ><HR><H1
  39461. ><A
  39462. NAME="security.magicquotes"
  39463. >Chapter 31. Magic Quotes</A
  39464. ></H1
  39465. ><P
  39466. >     Magic Quotes is a process that automagically escapes incoming data to the 
  39467.     PHP script. It's preferred to code with magic quotes off and to instead
  39468.     escape the data at runtime, as needed.
  39469.    </P
  39470. ><DIV
  39471. CLASS="sect1"
  39472. ><HR><H2
  39473. CLASS="sect1"
  39474. ><A
  39475. NAME="security.magicquotes.what"
  39476. >What are Magic Quotes</A
  39477. ></H2
  39478. ><P
  39479. >      When on, all <VAR
  39480. CLASS="literal"
  39481. >'</VAR
  39482. > (single-quote), <VAR
  39483. CLASS="literal"
  39484. >"</VAR
  39485. > 
  39486.      (double quote), <VAR
  39487. CLASS="literal"
  39488. >\</VAR
  39489. > (backslash) and <VAR
  39490. CLASS="literal"
  39491. >NULL</VAR
  39492. > 
  39493.      characters are escaped with a backslash automatically.  This is identical
  39494.      to what <A
  39495. HREF="#function.addslashes"
  39496. ><B
  39497. CLASS="function"
  39498. >addslashes()</B
  39499. ></A
  39500. > does.
  39501.     </P
  39502. ><P
  39503. >      There are three magic quote directives:
  39504.     </P
  39505. ><P
  39506. ></P
  39507. ><UL
  39508. ><LI
  39509. ><P
  39510. >        <A
  39511. HREF="#ini.magic-quotes-gpc"
  39512. >magic_quotes_gpc</A
  39513. >
  39514.       </P
  39515. ><P
  39516. >        Affects HTTP Request data (GET, POST, and COOKIE). Cannot be set at 
  39517.        runtime, and defaults to <SPAN
  39518. CLASS="emphasis"
  39519. ><I
  39520. CLASS="emphasis"
  39521. >on</I
  39522. ></SPAN
  39523. > in PHP.
  39524.       </P
  39525. ><P
  39526. >        See also <A
  39527. HREF="#function.get-magic-quotes-gpc"
  39528. ><B
  39529. CLASS="function"
  39530. >get_magic_quotes_gpc()</B
  39531. ></A
  39532. >.
  39533.       </P
  39534. ></LI
  39535. ><LI
  39536. ><P
  39537. >        <A
  39538. HREF="#ini.magic-quotes-runtime"
  39539. >magic_quotes_runtime</A
  39540. >
  39541.       </P
  39542. ><P
  39543. >        If enabled, most functions that return data from an external source, 
  39544.        including databases and text files, will have quotes escaped with a 
  39545.        backslash. Can be set at runtime, and defaults to <SPAN
  39546. CLASS="emphasis"
  39547. ><I
  39548. CLASS="emphasis"
  39549. >on</I
  39550. ></SPAN
  39551. >
  39552.        in PHP.
  39553.       </P
  39554. ><P
  39555. >        See also <A
  39556. HREF="#function.set-magic-quotes-runtime"
  39557. ><B
  39558. CLASS="function"
  39559. >set_magic_quotes_runtime()</B
  39560. ></A
  39561. > and
  39562.        <A
  39563. HREF="#function.get-magic-quotes-runtime"
  39564. ><B
  39565. CLASS="function"
  39566. >get_magic_quotes_runtime()</B
  39567. ></A
  39568. >.
  39569.       </P
  39570. ></LI
  39571. ><LI
  39572. ><P
  39573. >        <A
  39574. HREF="#ini.magic-quotes-sybase"
  39575. >magic_quotes_sybase</A
  39576. >
  39577.       </P
  39578. ><P
  39579. >        If enabled, a single-quote is escaped with a single-quote instead of a 
  39580.        backslash.  If on, it completely overrides 
  39581.        <A
  39582. HREF="#ini.magic-quotes-gpc"
  39583. >magic_quotes_gpc</A
  39584. >. Having 
  39585.        both directives enabled means only single quotes are escaped as 
  39586.        <VAR
  39587. CLASS="literal"
  39588. >''</VAR
  39589. >. Double quotes, backslashes and NULL's will 
  39590.        remain untouched and unescaped.
  39591.       </P
  39592. ><P
  39593. >        See also <A
  39594. HREF="#function.ini-get"
  39595. ><B
  39596. CLASS="function"
  39597. >ini_get()</B
  39598. ></A
  39599. > for retrieving its value.
  39600.       </P
  39601. ></LI
  39602. ></UL
  39603. ></DIV
  39604. ><DIV
  39605. CLASS="sect1"
  39606. ><HR><H2
  39607. CLASS="sect1"
  39608. ><A
  39609. NAME="security.magicquotes.why"
  39610. >Why use Magic Quotes</A
  39611. ></H2
  39612. ><P
  39613. ></P
  39614. ><UL
  39615. ><LI
  39616. ><P
  39617. >        Useful for beginners
  39618.       </P
  39619. ><P
  39620. >        Magic quotes are implemented in PHP to help code written by beginners 
  39621.        from being dangerous. Although 
  39622.        <A
  39623. HREF="#security.database.sql-injection"
  39624. >SQL Injection</A
  39625. > 
  39626.        is still possible with magic quotes on, the risk is reduced.
  39627.       </P
  39628. ></LI
  39629. ><LI
  39630. ><P
  39631. >        Convenience
  39632.       </P
  39633. ><P
  39634. >        For inserting data into a database, magic quotes essentially runs 
  39635.        <A
  39636. HREF="#function.addslashes"
  39637. ><B
  39638. CLASS="function"
  39639. >addslashes()</B
  39640. ></A
  39641. > on all Get, Post, and Cookie data,
  39642.        and does so automagically.
  39643.       </P
  39644. ></LI
  39645. ></UL
  39646. ></DIV
  39647. ><DIV
  39648. CLASS="sect1"
  39649. ><HR><H2
  39650. CLASS="sect1"
  39651. ><A
  39652. NAME="security.magicquotes.whynot"
  39653. >Why not to use Magic Quotes</A
  39654. ></H2
  39655. ><P
  39656. ></P
  39657. ><UL
  39658. ><LI
  39659. ><P
  39660. >        Portability
  39661.       </P
  39662. ><P
  39663. >        Assuming it to be on, or off, affects portability. Use
  39664.        <A
  39665. HREF="#function.get-magic-quotes-gpc"
  39666. ><B
  39667. CLASS="function"
  39668. >get_magic_quotes_gpc()</B
  39669. ></A
  39670. > to check for this, and code
  39671.        accordingly.
  39672.       </P
  39673. ></LI
  39674. ><LI
  39675. ><P
  39676. >        Performance
  39677.       </P
  39678. ><P
  39679. >        Because not every piece of escaped data is inserted into a 
  39680.        database, there is a performance loss for escaping all this data. 
  39681.        Simply calling on the escaping functions (like 
  39682.        <A
  39683. HREF="#function.addslashes"
  39684. ><B
  39685. CLASS="function"
  39686. >addslashes()</B
  39687. ></A
  39688. >) at runtime is more efficient.
  39689.       </P
  39690. ><P
  39691. >        Although <TT
  39692. CLASS="filename"
  39693. >php.ini-dist</TT
  39694. > enables these directives  
  39695.        by default, <TT
  39696. CLASS="filename"
  39697. >php.ini-recommended</TT
  39698. > disables it.
  39699.        This recommendation is mainly due to performance reasons.
  39700.       </P
  39701. ></LI
  39702. ><LI
  39703. ><P
  39704. >        Inconvenience
  39705.       </P
  39706. ><P
  39707. >        Because not all data needs escaping, it's often annoying to see escaped
  39708.        data where it shouldn't be. For example, emailing from a form, and
  39709.        seeing a bunch of \' within the email. To fix, this may require 
  39710.        excessive use of <A
  39711. HREF="#function.stripslashes"
  39712. ><B
  39713. CLASS="function"
  39714. >stripslashes()</B
  39715. ></A
  39716. >.
  39717.       </P
  39718. ></LI
  39719. ></UL
  39720. ></DIV
  39721. ><DIV
  39722. CLASS="sect1"
  39723. ><HR><H2
  39724. CLASS="sect1"
  39725. ><A
  39726. NAME="security.magicquotes.disabling"
  39727. >Disabling Magic Quotes</A
  39728. ></H2
  39729. ><P
  39730. >      The <A
  39731. HREF="#ini.magic-quotes-gpc"
  39732. >magic_quotes_gpc</A
  39733. >
  39734.      directive may only be disabled at the system level, and not at
  39735.      runtime. In otherwords, use of <A
  39736. HREF="#function.ini-set"
  39737. ><B
  39738. CLASS="function"
  39739. >ini_set()</B
  39740. ></A
  39741. > is not
  39742.      an option.
  39743.     </P
  39744. ><P
  39745. >      <TABLE
  39746. WIDTH="100%"
  39747. BORDER="0"
  39748. CELLPADDING="0"
  39749. CELLSPACING="0"
  39750. CLASS="EXAMPLE"
  39751. ><TR
  39752. ><TD
  39753. ><DIV
  39754. CLASS="example"
  39755. ><A
  39756. NAME="AEN6451"
  39757. ></A
  39758. ><P
  39759. ><B
  39760. >Example 31-1. Disabling magic quotes server side</B
  39761. ></P
  39762. ><P
  39763. >        An example that sets the value of these directives to 
  39764.        <VAR
  39765. CLASS="literal"
  39766. >Off</VAR
  39767. > in <TT
  39768. CLASS="filename"
  39769. >php.ini</TT
  39770. >.  For additional details, read the 
  39771.        manual section titled <A
  39772. HREF="#configuration.changes"
  39773. >How to 
  39774.        change configuration settings</A
  39775. >.
  39776.       </P
  39777. ><TABLE
  39778. BORDER="0"
  39779. BGCOLOR="#E0E0E0"
  39780. CELLPADDING="5"
  39781. ><TR
  39782. ><TD
  39783. ><PRE
  39784. CLASS="screen"
  39785. >; Magic quotes
  39786. ;
  39787.  
  39788. ; Magic quotes for incoming GET/POST/Cookie data.
  39789. magic_quotes_gpc = Off
  39790.  
  39791. ; Magic quotes for runtime-generated data, e.g. data from SQL, from exec(), etc.
  39792. magic_quotes_runtime = Off
  39793.  
  39794. ; Use Sybase-style magic quotes (escape ' with '' instead of \').
  39795. magic_quotes_sybase = Off</PRE
  39796. ></TD
  39797. ></TR
  39798. ></TABLE
  39799. ><P
  39800. >        If access to the server configuration is unavilable, use of
  39801.        <TT
  39802. CLASS="filename"
  39803. >.htaccess</TT
  39804. > is also an option.  For example:
  39805.       </P
  39806. ><TABLE
  39807. BORDER="0"
  39808. BGCOLOR="#E0E0E0"
  39809. CELLPADDING="5"
  39810. ><TR
  39811. ><TD
  39812. ><PRE
  39813. CLASS="screen"
  39814. >php_flag magic_quotes_gpc Off</PRE
  39815. ></TD
  39816. ></TR
  39817. ></TABLE
  39818. ></DIV
  39819. ></TD
  39820. ></TR
  39821. ></TABLE
  39822. >
  39823.     </P
  39824. ><P
  39825. >      In the interest of writing portable code (code that works in any 
  39826.      environment), like if setting at the server level is not possible,
  39827.      here's an example to disable <A
  39828. HREF="#ini.magic-quotes-gpc"
  39829. >      magic_quotes_gpc</A
  39830. > at runtime. This method is inefficient so 
  39831.      it's preferred to instead set the appropriate directives elsewhere.
  39832.     </P
  39833. ><P
  39834. >      <TABLE
  39835. WIDTH="100%"
  39836. BORDER="0"
  39837. CELLPADDING="0"
  39838. CELLSPACING="0"
  39839. CLASS="EXAMPLE"
  39840. ><TR
  39841. ><TD
  39842. ><DIV
  39843. CLASS="example"
  39844. ><A
  39845. NAME="AEN6464"
  39846. ></A
  39847. ><P
  39848. ><B
  39849. >Example 31-2. Disabling magic quotes at runtime</B
  39850. ></P
  39851. ><TABLE
  39852. BORDER="0"
  39853. BGCOLOR="#E0E0E0"
  39854. CELLPADDING="5"
  39855. ><TR
  39856. ><TD
  39857. ><PRE
  39858. CLASS="php"
  39859. ><?php
  39860. if (get_magic_quotes_gpc()) {
  39861.     function stripslashes_deep($value)
  39862.     {
  39863.         $value = is_array($value) ?
  39864.                     array_map('stripslashes_deep', $value) :
  39865.                     stripslashes($value);
  39866.  
  39867.         return $value;
  39868.     }
  39869.  
  39870.     $_POST = array_map('stripslashes_deep', $_POST);
  39871.     $_GET = array_map('stripslashes_deep', $_GET);
  39872.     $_COOKIE = array_map('stripslashes_deep', $_COOKIE);
  39873. }
  39874. ?></PRE
  39875. ></TD
  39876. ></TR
  39877. ></TABLE
  39878. ></DIV
  39879. ></TD
  39880. ></TR
  39881. ></TABLE
  39882. >
  39883.     </P
  39884. ></DIV
  39885. ></DIV
  39886. ><DIV
  39887. CLASS="chapter"
  39888. ><HR><H1
  39889. ><A
  39890. NAME="security.hiding"
  39891. >Chapter 32. Hiding PHP</A
  39892. ></H1
  39893. ><P
  39894. >     In general, security by obscurity is one of the weakest forms of security.
  39895.     But in some cases, every little bit of extra security is desirable.
  39896.    </P
  39897. ><P
  39898. >     A few simple techniques can help to hide PHP, possibly slowing
  39899.     down an attacker who is attempting to discover weaknesses in your
  39900.     system. By setting expose_php = off in your <TT
  39901. CLASS="filename"
  39902. >php.ini</TT
  39903. > file, you
  39904.     reduce the amount of information available to them.
  39905.    </P
  39906. ><P
  39907. >     Another tactic is to configure web servers such as apache to
  39908.     parse different filetypes through PHP, either with an <TT
  39909. CLASS="filename"
  39910. >.htaccess</TT
  39911. >
  39912.     directive, or in the apache configuration file itself. You can
  39913.     then use misleading file extensions:
  39914.     <TABLE
  39915. WIDTH="100%"
  39916. BORDER="0"
  39917. CELLPADDING="0"
  39918. CELLSPACING="0"
  39919. CLASS="EXAMPLE"
  39920. ><TR
  39921. ><TD
  39922. ><DIV
  39923. CLASS="example"
  39924. ><A
  39925. NAME="AEN6474"
  39926. ></A
  39927. ><P
  39928. ><B
  39929. >Example 32-1. Hiding PHP as another language</B
  39930. ></P
  39931. ><TABLE
  39932. BORDER="0"
  39933. BGCOLOR="#E0E0E0"
  39934. CELLPADDING="5"
  39935. ><TR
  39936. ><TD
  39937. ><PRE
  39938. CLASS="apache-conf"
  39939. ># Make PHP code look like other code types
  39940. AddType application/x-httpd-php .asp .py .pl</PRE
  39941. ></TD
  39942. ></TR
  39943. ></TABLE
  39944. ></DIV
  39945. ></TD
  39946. ></TR
  39947. ></TABLE
  39948. >
  39949.     Or obscure it completely:
  39950.     <TABLE
  39951. WIDTH="100%"
  39952. BORDER="0"
  39953. CELLPADDING="0"
  39954. CELLSPACING="0"
  39955. CLASS="EXAMPLE"
  39956. ><TR
  39957. ><TD
  39958. ><DIV
  39959. CLASS="example"
  39960. ><A
  39961. NAME="AEN6477"
  39962. ></A
  39963. ><P
  39964. ><B
  39965. >Example 32-2. Using unknown types for PHP extensions</B
  39966. ></P
  39967. ><TABLE
  39968. BORDER="0"
  39969. BGCOLOR="#E0E0E0"
  39970. CELLPADDING="5"
  39971. ><TR
  39972. ><TD
  39973. ><PRE
  39974. CLASS="apache-conf"
  39975. ># Make PHP code look like unknown types
  39976. AddType application/x-httpd-php .bop .foo .133t</PRE
  39977. ></TD
  39978. ></TR
  39979. ></TABLE
  39980. ></DIV
  39981. ></TD
  39982. ></TR
  39983. ></TABLE
  39984. >
  39985.     Or hide it as HTML code, which has a slight performance hit because
  39986.     all HTML will be parsed through the PHP engine:
  39987.     <TABLE
  39988. WIDTH="100%"
  39989. BORDER="0"
  39990. CELLPADDING="0"
  39991. CELLSPACING="0"
  39992. CLASS="EXAMPLE"
  39993. ><TR
  39994. ><TD
  39995. ><DIV
  39996. CLASS="example"
  39997. ><A
  39998. NAME="AEN6480"
  39999. ></A
  40000. ><P
  40001. ><B
  40002. >Example 32-3. Using HTML types for PHP extensions</B
  40003. ></P
  40004. ><TABLE
  40005. BORDER="0"
  40006. BGCOLOR="#E0E0E0"
  40007. CELLPADDING="5"
  40008. ><TR
  40009. ><TD
  40010. ><PRE
  40011. CLASS="apache-conf"
  40012. ># Make all PHP code look like HTML
  40013. AddType application/x-httpd-php .htm .html</PRE
  40014. ></TD
  40015. ></TR
  40016. ></TABLE
  40017. ></DIV
  40018. ></TD
  40019. ></TR
  40020. ></TABLE
  40021. >
  40022.     For this to work effectively, you must rename your PHP files with
  40023.     the above extensions. While it is a form of security through
  40024.     obscurity, it's a minor preventative measure with few drawbacks.
  40025.    </P
  40026. ></DIV
  40027. ><DIV
  40028. CLASS="chapter"
  40029. ><HR><H1
  40030. ><A
  40031. NAME="security.current"
  40032. >Chapter 33. Keeping Current</A
  40033. ></H1
  40034. ><P
  40035. >     PHP, like any other large system, is under constant scrutiny and
  40036.     improvement. Each new version will often include both major and
  40037.     minor changes to enhance and repair security flaws, configuration
  40038.     mishaps, and other issues that will affect the overall security
  40039.     and stability of your system.
  40040.    </P
  40041. ><P
  40042. >     Like other system-level scripting languages and programs, the best
  40043.     approach is to update often, and maintain awareness of the latest
  40044.     versions and their changes.
  40045.    </P
  40046. ></DIV
  40047. ></DIV
  40048. ><DIV
  40049. CLASS="PART"
  40050. ><A
  40051. NAME="features"
  40052. ></A
  40053. ><DIV
  40054. CLASS="TITLEPAGE"
  40055. ><H1
  40056. CLASS="title"
  40057. >V. Features</H1
  40058. ><DIV
  40059. CLASS="TOC"
  40060. ><DL
  40061. ><DT
  40062. ><B
  40063. >Table of Contents</B
  40064. ></DT
  40065. ><DT
  40066. >34. <A
  40067. HREF="#features.http-auth"
  40068. >HTTP authentication with PHP</A
  40069. ></DT
  40070. ><DT
  40071. >35. <A
  40072. HREF="#features.cookies"
  40073. >Cookies</A
  40074. ></DT
  40075. ><DT
  40076. >36. <A
  40077. HREF="#features.sessions"
  40078. >Sessions</A
  40079. ></DT
  40080. ><DT
  40081. >37. <A
  40082. HREF="#features.xforms"
  40083. >Dealing with XForms</A
  40084. ></DT
  40085. ><DT
  40086. >38. <A
  40087. HREF="#features.file-upload"
  40088. >Handling file uploads</A
  40089. ></DT
  40090. ><DT
  40091. >39. <A
  40092. HREF="#features.remote-files"
  40093. >Using remote files</A
  40094. ></DT
  40095. ><DT
  40096. >40. <A
  40097. HREF="#features.connection-handling"
  40098. >Connection handling</A
  40099. ></DT
  40100. ><DT
  40101. >41. <A
  40102. HREF="#features.persistent-connections"
  40103. >Persistent Database Connections</A
  40104. ></DT
  40105. ><DT
  40106. >42. <A
  40107. HREF="#features.safe-mode"
  40108. >Safe Mode</A
  40109. ></DT
  40110. ><DT
  40111. >43. <A
  40112. HREF="#features.commandline"
  40113. >Using PHP from the command line</A
  40114. ></DT
  40115. ></DL
  40116. ></DIV
  40117. ></DIV
  40118. ><DIV
  40119. CLASS="chapter"
  40120. ><HR><H1
  40121. ><A
  40122. NAME="features.http-auth"
  40123. >Chapter 34. HTTP authentication with PHP</A
  40124. ></H1
  40125. ><P
  40126. >    The <ACRONYM
  40127. CLASS="acronym"
  40128. >HTTP</ACRONYM
  40129. > Authentication hooks in PHP are only available when it is
  40130.    running as an Apache module and is hence not available in the CGI version.
  40131.    In an Apache module PHP script, it is possible to use the 
  40132.    <A
  40133. HREF="#function.header"
  40134. ><B
  40135. CLASS="function"
  40136. >header()</B
  40137. ></A
  40138. > function to send an "Authentication Required" 
  40139.    message to the client browser causing it to pop up a Username/Password 
  40140.    input window.  Once the user has filled in a username and a password, 
  40141.    the URL containing the PHP script will be called again with the 
  40142.    <A
  40143. HREF="#reserved.variables"
  40144. >predefined variables</A
  40145. > 
  40146.    <VAR
  40147. CLASS="varname"
  40148. >PHP_AUTH_USER</VAR
  40149. >, <VAR
  40150. CLASS="varname"
  40151. >PHP_AUTH_PW</VAR
  40152. >, 
  40153.    and <VAR
  40154. CLASS="varname"
  40155. >AUTH_TYPE</VAR
  40156. > set to the user name, password and 
  40157.    authentication type respectively.  These predefined variables are found 
  40158.    in the <A
  40159. HREF="#reserved.variables.server"
  40160. >$_SERVER</A
  40161. > and 
  40162.    <VAR
  40163. CLASS="varname"
  40164. >$HTTP_SERVER_VARS</VAR
  40165. > arrays.  Only "Basic" authentication 
  40166.    is supported. See the <A
  40167. HREF="#function.header"
  40168. ><B
  40169. CLASS="function"
  40170. >header()</B
  40171. ></A
  40172. > function for more 
  40173.    information.
  40174.   </P
  40175. ><DIV
  40176. CLASS="note"
  40177. ><BLOCKQUOTE
  40178. CLASS="note"
  40179. ><P
  40180. ><B
  40181. >PHP Version Note: </B
  40182. >
  40183.     <A
  40184. HREF="#language.variables.superglobals"
  40185. >Autoglobals</A
  40186. >, 
  40187.     such as <A
  40188. HREF="#reserved.variables.server"
  40189. >$_SERVER</A
  40190. >, became 
  40191.     available in PHP <A
  40192. HREF="http://www.php.net/release_4_1_0.php"
  40193. TARGET="_top"
  40194. >4.1.0</A
  40195. >. 
  40196.     <VAR
  40197. CLASS="varname"
  40198. >$HTTP_SERVER_VARS</VAR
  40199. > has been available since PHP 3.
  40200.    </P
  40201. ></BLOCKQUOTE
  40202. ></DIV
  40203. ><P
  40204. >    An example script fragment which would force client authentication
  40205.    on a page is as follows:
  40206.   </P
  40207. ><P
  40208. >    <TABLE
  40209. WIDTH="100%"
  40210. BORDER="0"
  40211. CELLPADDING="0"
  40212. CELLSPACING="0"
  40213. CLASS="EXAMPLE"
  40214. ><TR
  40215. ><TD
  40216. ><DIV
  40217. CLASS="example"
  40218. ><A
  40219. NAME="AEN6510"
  40220. ></A
  40221. ><P
  40222. ><B
  40223. >Example 34-1. HTTP Authentication example</B
  40224. ></P
  40225. ><TABLE
  40226. BORDER="0"
  40227. BGCOLOR="#E0E0E0"
  40228. CELLPADDING="5"
  40229. ><TR
  40230. ><TD
  40231. ><PRE
  40232. CLASS="php"
  40233. ><?php
  40234.   if (!isset($_SERVER['PHP_AUTH_USER'])) {
  40235.     header('WWW-Authenticate: Basic realm="My Realm"');
  40236.     header('HTTP/1.0 401 Unauthorized');
  40237.     echo 'Text to send if user hits Cancel button';
  40238.     exit;
  40239.   } else {
  40240.     echo "<p>Hello {$_SERVER['PHP_AUTH_USER']}.</p>";
  40241.     echo "<p>You entered {$_SERVER['PHP_AUTH_PW']} as your password.</p>";
  40242.   }
  40243. ?></PRE
  40244. ></TD
  40245. ></TR
  40246. ></TABLE
  40247. ></DIV
  40248. ></TD
  40249. ></TR
  40250. ></TABLE
  40251. >
  40252.   </P
  40253. ><DIV
  40254. CLASS="note"
  40255. ><BLOCKQUOTE
  40256. CLASS="note"
  40257. ><P
  40258. ><B
  40259. >Compatibility Note: </B
  40260. >
  40261.     Please be careful when coding the HTTP header lines. In order to guarantee maximum
  40262.     compatibility with all clients, the keyword "Basic" should be written with an
  40263.     uppercase "B", the realm string must be enclosed in double (not single) quotes,
  40264.     and exactly one space should precede the <SPAN
  40265. CLASS="emphasis"
  40266. ><I
  40267. CLASS="emphasis"
  40268. >401</I
  40269. ></SPAN
  40270. > code in the 
  40271.     <SPAN
  40272. CLASS="emphasis"
  40273. ><I
  40274. CLASS="emphasis"
  40275. >HTTP/1.0 401</I
  40276. ></SPAN
  40277. > header line.
  40278.    </P
  40279. ></BLOCKQUOTE
  40280. ></DIV
  40281. ><P
  40282. >    Instead of simply printing out <VAR
  40283. CLASS="varname"
  40284. >PHP_AUTH_USER</VAR
  40285. > 
  40286.    and <VAR
  40287. CLASS="varname"
  40288. >PHP_AUTH_PW</VAR
  40289. >, as done in the above example, 
  40290.    you may want to check the username and password for validity.  
  40291.    Perhaps by sending a query to a database, or by looking up the 
  40292.    user in a dbm file.
  40293.   </P
  40294. ><P
  40295. >    Watch out for buggy Internet Explorer browsers out there.  They
  40296.    seem very picky about the order of the headers.  Sending the
  40297.    <SPAN
  40298. CLASS="emphasis"
  40299. ><I
  40300. CLASS="emphasis"
  40301. >WWW-Authenticate</I
  40302. ></SPAN
  40303. > header before the
  40304.    <VAR
  40305. CLASS="literal"
  40306. >HTTP/1.0 401</VAR
  40307. > header seems to do the trick
  40308.    for now.
  40309.   </P
  40310. ><P
  40311. >    As of PHP 4.3.0, in order to prevent someone from writing a script which
  40312.    reveals the password for a page that was authenticated through a
  40313.    traditional external mechanism, the PHP_AUTH variables will not be 
  40314.    set if external authentication is enabled for that particular
  40315.    page and <A
  40316. HREF="#ini.safe-mode"
  40317. >safe mode</A
  40318. > is enabled.  Regardless, 
  40319.    <VAR
  40320. CLASS="varname"
  40321. >REMOTE_USER</VAR
  40322. > can be used 
  40323.    to identify the externally-authenticated user.  So, you can use  
  40324.    <VAR
  40325. CLASS="varname"
  40326. >$_SERVER['REMOTE_USER']</VAR
  40327. >.
  40328.   </P
  40329. ><DIV
  40330. CLASS="note"
  40331. ><BLOCKQUOTE
  40332. CLASS="note"
  40333. ><P
  40334. ><B
  40335. >Configuration Note: </B
  40336. >
  40337.     PHP uses the presence of an <VAR
  40338. CLASS="literal"
  40339. >AuthType</VAR
  40340. > directive
  40341.     to determine whether external authentication is in effect.
  40342.    </P
  40343. ></BLOCKQUOTE
  40344. ></DIV
  40345. ><P
  40346. >    Note, however, that the above does not prevent someone who
  40347.    controls a non-authenticated URL from stealing passwords from
  40348.    authenticated URLs on the same server.
  40349.   </P
  40350. ><P
  40351. >    Both Netscape Navigator and Internet Explorer will clear the local browser
  40352.    window's authentication cache for the realm upon receiving a
  40353.    server response of 401. This can effectively "log out" a user,
  40354.    forcing them to re-enter their username and password. Some people
  40355.    use this to "time out" logins, or provide a "log-out" button.
  40356.   </P
  40357. ><P
  40358. >    <TABLE
  40359. WIDTH="100%"
  40360. BORDER="0"
  40361. CELLPADDING="0"
  40362. CELLSPACING="0"
  40363. CLASS="EXAMPLE"
  40364. ><TR
  40365. ><TD
  40366. ><DIV
  40367. CLASS="example"
  40368. ><A
  40369. NAME="AEN6535"
  40370. ></A
  40371. ><P
  40372. ><B
  40373. >Example 34-2. HTTP Authentication example forcing a new name/password</B
  40374. ></P
  40375. ><TABLE
  40376. BORDER="0"
  40377. BGCOLOR="#E0E0E0"
  40378. CELLPADDING="5"
  40379. ><TR
  40380. ><TD
  40381. ><PRE
  40382. CLASS="php"
  40383. ><?php
  40384.   function authenticate() {
  40385.     header('WWW-Authenticate: Basic realm="Test Authentication System"');
  40386.     header('HTTP/1.0 401 Unauthorized');
  40387.     echo "You must enter a valid login ID and password to access this resource\n";
  40388.     exit;
  40389.   }
  40390.  
  40391.   if (!isset($_SERVER['PHP_AUTH_USER']) ||
  40392.       ($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
  40393.    authenticate();
  40394.   } 
  40395.   else {
  40396.    echo "<p>Welcome: {$_SERVER['PHP_AUTH_USER']}<br />";
  40397.    echo "Old: {$_REQUEST['OldAuth']}";
  40398.    echo "<form action='{$_SERVER['PHP_SELF']}' METHOD='post'>\n";
  40399.    echo "<input type='hidden' name='SeenBefore' value='1' />\n";
  40400.    echo "<input type='hidden' name='OldAuth' value='{$_SERVER['PHP_AUTH_USER']}' />\n";
  40401.    echo "<input type='submit' value='Re Authenticate' />\n";
  40402.    echo "</form></p>\n";
  40403.   }
  40404. ?></PRE
  40405. ></TD
  40406. ></TR
  40407. ></TABLE
  40408. ></DIV
  40409. ></TD
  40410. ></TR
  40411. ></TABLE
  40412. >
  40413.   </P
  40414. ><P
  40415. >    This behavior is not required by the HTTP Basic authentication
  40416.    standard, so you should never depend on this. Testing with Lynx
  40417.    has shown that Lynx does not clear the authentication credentials
  40418.    with a 401 server response, so pressing back and then forward
  40419.    again will open the resource as long as the credential
  40420.    requirements haven't changed. The user can press the
  40421.    '_' key to clear their authentication information, however.
  40422.   </P
  40423. ><P
  40424. >    Also note that until PHP 4.3.3, HTTP Authentication did not work
  40425.    using Microsoft's IIS server with the CGI version of PHP due to a
  40426.    limitation of IIS.  In order to get it to work in PHP 4.3.3+, 
  40427.    you must edit your IIS configuration "Directory Security".  Click
  40428.    on "Edit" and only check "Anonymous Access", all other fields
  40429.    should be left unchecked.
  40430.   </P
  40431. ><P
  40432. >    Another limitation is if you're using the IIS module (ISAPI) and PHP 4, you
  40433.    may not use the <VAR
  40434. CLASS="literal"
  40435. >PHP_AUTH_*</VAR
  40436. > variables but instead, the
  40437.    variable <VAR
  40438. CLASS="literal"
  40439. >HTTP_AUTHORIZATION</VAR
  40440. > is available.  For example,
  40441.    consider the following code: <VAR
  40442. CLASS="literal"
  40443. >list($user, $pw) = explode(':',
  40444.     base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));</VAR
  40445. >
  40446.   </P
  40447. ><DIV
  40448. CLASS="note"
  40449. ><BLOCKQUOTE
  40450. CLASS="note"
  40451. ><P
  40452. ><B
  40453. >IIS Note:: </B
  40454. >
  40455.     For HTTP Authentication to work with IIS, the PHP directive
  40456.     <A
  40457. HREF="#ini.cgi.rfc2616-headers"
  40458. >cgi.rfc2616_headers</A
  40459. > must
  40460.     be set to <VAR
  40461. CLASS="literal"
  40462. >0</VAR
  40463. > (the default value).
  40464.    </P
  40465. ></BLOCKQUOTE
  40466. ></DIV
  40467. ><DIV
  40468. CLASS="note"
  40469. ><BLOCKQUOTE
  40470. CLASS="note"
  40471. ><P
  40472. ><B
  40473. >Note: </B
  40474. >
  40475.     If <A
  40476. HREF="#ini.safe-mode"
  40477. >safe mode</A
  40478. > is enabled, the
  40479.     uid of the script is added to the <VAR
  40480. CLASS="literal"
  40481. >realm</VAR
  40482. > part of
  40483.     the <VAR
  40484. CLASS="literal"
  40485. >WWW-Authenticate</VAR
  40486. > header.
  40487.    </P
  40488. ></BLOCKQUOTE
  40489. ></DIV
  40490. ></DIV
  40491. ><DIV
  40492. CLASS="chapter"
  40493. ><HR><H1
  40494. ><A
  40495. NAME="features.cookies"
  40496. >Chapter 35. Cookies</A
  40497. ></H1
  40498. ><P
  40499. >    PHP transparently supports <ACRONYM
  40500. CLASS="acronym"
  40501. >HTTP</ACRONYM
  40502. > cookies.  Cookies are a mechanism for
  40503.    storing data in the remote browser and thus tracking or identifying return
  40504.    users.  You can set cookies using the <A
  40505. HREF="#function.setcookie"
  40506. ><B
  40507. CLASS="function"
  40508. >setcookie()</B
  40509. ></A
  40510. > or
  40511.    <A
  40512. HREF="#function.setrawcookie"
  40513. ><B
  40514. CLASS="function"
  40515. >setrawcookie()</B
  40516. ></A
  40517. >
  40518.    function.  Cookies are part of the <ACRONYM
  40519. CLASS="acronym"
  40520. >HTTP</ACRONYM
  40521. > header, so
  40522.    <A
  40523. HREF="#function.setcookie"
  40524. ><B
  40525. CLASS="function"
  40526. >setcookie()</B
  40527. ></A
  40528. > must be called before any output is sent to
  40529.    the browser.  This is the same limitation that <A
  40530. HREF="#function.header"
  40531. ><B
  40532. CLASS="function"
  40533. >header()</B
  40534. ></A
  40535. >
  40536.    has. You can use the <A
  40537. HREF="#ref.outcontrol"
  40538. >output buffering
  40539.    functions</A
  40540. > to delay the script output until you have decided whether
  40541.    or not to set any cookies or send any headers.
  40542.   </P
  40543. ><P
  40544. >    Any cookies sent to you from the client will automatically be turned into a
  40545.    PHP variable just like <VAR
  40546. CLASS="literal"
  40547. >GET</VAR
  40548. > and <VAR
  40549. CLASS="literal"
  40550. >POST</VAR
  40551. > 
  40552.    method data, depending on the  <A
  40553. HREF="#ini.register-globals"
  40554. >register_globals</A
  40555. >
  40556.    and <A
  40557. HREF="#ini.variables-order"
  40558. >variables_order</A
  40559. >
  40560.    configuration variables.  If you wish to assign multiple values to a single
  40561.    cookie, just add <VAR
  40562. CLASS="literal"
  40563. >[]</VAR
  40564. > to the cookie name.
  40565.   </P
  40566. ><P
  40567. >    In PHP 4.1.0 and later, the <VAR
  40568. CLASS="varname"
  40569. >$_COOKIE</VAR
  40570. > auto-global array
  40571.    will always be set with any cookies sent from the client.
  40572.    <VAR
  40573. CLASS="varname"
  40574. >$HTTP_COOKIE_VARS</VAR
  40575. > is also set in earlier versions of PHP
  40576.    when the <A
  40577. HREF="#ini.track-vars"
  40578. >track_vars</A
  40579. > configuration 
  40580.    variable is set. (This setting is always on since PHP 4.0.3.)
  40581.   </P
  40582. ><P
  40583. >    For more details, including notes on browser bugs, see the
  40584.    <A
  40585. HREF="#function.setcookie"
  40586. ><B
  40587. CLASS="function"
  40588. >setcookie()</B
  40589. ></A
  40590. > and <A
  40591. HREF="#function.setrawcookie"
  40592. ><B
  40593. CLASS="function"
  40594. >setrawcookie()</B
  40595. ></A
  40596. >
  40597.    function.
  40598.   </P
  40599. ></DIV
  40600. ><DIV
  40601. CLASS="chapter"
  40602. ><HR><H1
  40603. ><A
  40604. NAME="features.sessions"
  40605. >Chapter 36. Sessions</A
  40606. ></H1
  40607. ><P
  40608. >    Session support in PHP consists of a way to preserve certain data across
  40609.    subsequent accesses. This enables you to build more customized applications
  40610.    and increase the appeal of your web site. All informations are in
  40611.    <A
  40612. HREF="#ref.session"
  40613. >Session reference</A
  40614. > sections.
  40615.   </P
  40616. ></DIV
  40617. ><DIV
  40618. CLASS="chapter"
  40619. ><HR><H1
  40620. ><A
  40621. NAME="features.xforms"
  40622. >Chapter 37. Dealing with XForms</A
  40623. ></H1
  40624. ><P
  40625. >   <A
  40626. HREF="http://www.w3.org/MarkUp/Forms/"
  40627. TARGET="_top"
  40628. >XForms</A
  40629. > defines a variation on traditional
  40630.   webforms which allows them to be used on a wider variety of platforms and 
  40631.   browsers or even non-traditional media such as PDF documents.
  40632.  </P
  40633. ><P
  40634. >   The first key difference in XForms is how the form is sent to the client.
  40635.   <A
  40636. HREF="http://www.w3.org/MarkUp/Forms/2003/xforms-for-html-authors.html"
  40637. TARGET="_top"
  40638. >XForms for HTML Authors</A
  40639. >
  40640.   contains a detailed description of how to create XForms, for the purpose
  40641.   of this tutorial we'll only be looking at a simple example.
  40642.  </P
  40643. ><TABLE
  40644. WIDTH="100%"
  40645. BORDER="0"
  40646. CELLPADDING="0"
  40647. CELLSPACING="0"
  40648. CLASS="EXAMPLE"
  40649. ><TR
  40650. ><TD
  40651. ><DIV
  40652. CLASS="example"
  40653. ><A
  40654. NAME="AEN6587"
  40655. ></A
  40656. ><P
  40657. ><B
  40658. >Example 37-1. A simple XForms search form</B
  40659. ></P
  40660. ><TABLE
  40661. BORDER="0"
  40662. BGCOLOR="#E0E0E0"
  40663. CELLPADDING="5"
  40664. ><TR
  40665. ><TD
  40666. ><PRE
  40667. CLASS="html"
  40668. ><h:html xmlns:h="http://www.w3.org/1999/xhtml"
  40669.         xmlns="http://www.w3.org/2002/xforms">
  40670. <h:head>
  40671.  <h:title>Search</h:title>
  40672.  <model>
  40673.   <submission action="http://example.com/search"
  40674.               method="post" id="s"/>
  40675.  </model>
  40676. </h:head>
  40677. <h:body>
  40678.  <h:p>
  40679.   <input ref="q"><label>Find</label></input>
  40680.   <submit submission="s"><label>Go</label></submit>
  40681.  </h:p>
  40682. </h:body>
  40683. </h:html></PRE
  40684. ></TD
  40685. ></TR
  40686. ></TABLE
  40687. ></DIV
  40688. ></TD
  40689. ></TR
  40690. ></TABLE
  40691. ><P
  40692. >   The above form displays a text input box (named <VAR
  40693. CLASS="parameter"
  40694. >q</VAR
  40695. >),
  40696.   and a submit button.  When the submit button is clicked, the form will be
  40697.   sent to the page referred to by <VAR
  40698. CLASS="literal"
  40699. >action</VAR
  40700. >.
  40701.  </P
  40702. ><P
  40703. >   Here's where it starts to look different from your web application's point
  40704.   of view.  In a normal HTML form, the data would be sent as 
  40705.   <VAR
  40706. CLASS="literal"
  40707. >application/x-www-form-urlencoded</VAR
  40708. >, in the XForms world
  40709.   however, this information is sent as XML formatted data.
  40710.  </P
  40711. ><P
  40712. >   If you're choosing to work with XForms then you probably want that data as
  40713.   XML, in that case, look in <VAR
  40714. CLASS="varname"
  40715. >$HTTP_RAW_POST_DATA</VAR
  40716. > where
  40717.   you'll find the XML document generated by the browser which you can pass
  40718.   into your favorite XSLT engine or document parser.
  40719.  </P
  40720. ><P
  40721. >   If you're not interested in formatting and just want your data to be loaded
  40722.   into the traditional <VAR
  40723. CLASS="varname"
  40724. >$_POST</VAR
  40725. > variable, you can instruct
  40726.   the client browser to send it as <VAR
  40727. CLASS="literal"
  40728. >application/x-www-form-urlencoded</VAR
  40729. >
  40730.   by changing the <VAR
  40731. CLASS="parameter"
  40732. >method</VAR
  40733. > attribute to
  40734.   <SPAN
  40735. CLASS="emphasis"
  40736. ><I
  40737. CLASS="emphasis"
  40738. >urlencoded-post</I
  40739. ></SPAN
  40740. >.
  40741.  </P
  40742. ><TABLE
  40743. WIDTH="100%"
  40744. BORDER="0"
  40745. CELLPADDING="0"
  40746. CELLSPACING="0"
  40747. CLASS="EXAMPLE"
  40748. ><TR
  40749. ><TD
  40750. ><DIV
  40751. CLASS="example"
  40752. ><A
  40753. NAME="AEN6602"
  40754. ></A
  40755. ><P
  40756. ><B
  40757. >Example 37-2. Using an XForm to populate <VAR
  40758. CLASS="varname"
  40759. >$_POST</VAR
  40760. ></B
  40761. ></P
  40762. ><TABLE
  40763. BORDER="0"
  40764. BGCOLOR="#E0E0E0"
  40765. CELLPADDING="5"
  40766. ><TR
  40767. ><TD
  40768. ><PRE
  40769. CLASS="html"
  40770. ><h:html xmlns:h="http://www.w3.org/1999/xhtml"
  40771.         xmlns="http://www.w3.org/2002/xforms">
  40772. <h:head>
  40773.  <h:title>Search</h:title>
  40774.  <model>
  40775.   <submission action="http://example.com/search"
  40776.               method="urlencoded-post" id="s"/>
  40777.  </model>
  40778. </h:head>
  40779. <h:body>
  40780.  <h:p>
  40781.   <input ref="q"><label>Find</label></input>
  40782.   <submit submission="s"><label>Go</label></submit>
  40783.  </h:p>
  40784. </h:body>
  40785. </h:html></PRE
  40786. ></TD
  40787. ></TR
  40788. ></TABLE
  40789. ></DIV
  40790. ></TD
  40791. ></TR
  40792. ></TABLE
  40793. ><DIV
  40794. CLASS="note"
  40795. ><BLOCKQUOTE
  40796. CLASS="note"
  40797. ><P
  40798. ><B
  40799. >Note: </B
  40800. >
  40801.    As of this writing, many browsers do not support XForms.
  40802.    Check your browser version if the above examples fails.
  40803.   </P
  40804. ></BLOCKQUOTE
  40805. ></DIV
  40806. ></DIV
  40807. ><DIV
  40808. CLASS="chapter"
  40809. ><HR><H1
  40810. ><A
  40811. NAME="features.file-upload"
  40812. >Chapter 38. Handling file uploads</A
  40813. ></H1
  40814. ><DIV
  40815. CLASS="sect1"
  40816. ><H2
  40817. CLASS="sect1"
  40818. ><A
  40819. NAME="features.file-upload.post-method"
  40820. >POST method uploads</A
  40821. ></H2
  40822. ><P
  40823. >     This feature lets people upload both text and binary files. 
  40824.     With PHP's authentication and file manipulation functions,
  40825.     you have full control over who is allowed to upload and
  40826.     what is to be done with the file once it has been uploaded.
  40827.    </P
  40828. ><P
  40829. >     PHP is capable of receiving file uploads from any RFC-1867
  40830.     compliant browser (which includes <SPAN
  40831. CLASS="productname"
  40832. >Netscape Navigator 3</SPAN
  40833. > 
  40834.     or later, <SPAN
  40835. CLASS="productname"
  40836. >Microsoft Internet Explorer 3</SPAN
  40837. > 
  40838.     with a patch from Microsoft, or later without a patch).
  40839.    </P
  40840. ><DIV
  40841. CLASS="note"
  40842. ><BLOCKQUOTE
  40843. CLASS="note"
  40844. ><P
  40845. ><B
  40846. >Related Configurations Note: </B
  40847. >
  40848.      See also the <A
  40849. HREF="#ini.file-uploads"
  40850. >file_uploads</A
  40851. >, 
  40852.      <A
  40853. HREF="#ini.upload-max-filesize"
  40854. >upload_max_filesize</A
  40855. >,
  40856.      <A
  40857. HREF="#ini.upload-tmp-dir"
  40858. >upload_tmp_dir</A
  40859. >,
  40860.      <A
  40861. HREF="#ini.post-max-size"
  40862. >post_max_size</A
  40863. > and
  40864.      <A
  40865. HREF="#ini.max-input-time"
  40866. >max_input_time</A
  40867. > directives 
  40868.      in <TT
  40869. CLASS="filename"
  40870. >php.ini</TT
  40871. >
  40872.     </P
  40873. ></BLOCKQUOTE
  40874. ></DIV
  40875. ><P
  40876. >     PHP also supports PUT-method file uploads as used by
  40877.     <SPAN
  40878. CLASS="productname"
  40879. >Netscape Composer</SPAN
  40880. > and W3C's 
  40881.     <SPAN
  40882. CLASS="productname"
  40883. >Amaya</SPAN
  40884. > clients.  See the <A
  40885. HREF="#features.file-upload.put-method"
  40886. >PUT Method
  40887.     Support</A
  40888. > for more details.
  40889.    </P
  40890. ><P
  40891. >     <TABLE
  40892. WIDTH="100%"
  40893. BORDER="0"
  40894. CELLPADDING="0"
  40895. CELLSPACING="0"
  40896. CLASS="EXAMPLE"
  40897. ><TR
  40898. ><TD
  40899. ><DIV
  40900. CLASS="example"
  40901. ><A
  40902. NAME="AEN6630"
  40903. ></A
  40904. ><P
  40905. ><B
  40906. >Example 38-1. File Upload Form</B
  40907. ></P
  40908. ><P
  40909. >       A file upload screen can be built by creating a special form which
  40910.       looks something like this:
  40911.      </P
  40912. ><TABLE
  40913. BORDER="0"
  40914. BGCOLOR="#E0E0E0"
  40915. CELLPADDING="5"
  40916. ><TR
  40917. ><TD
  40918. ><PRE
  40919. CLASS="html"
  40920. ><!-- The data encoding type, enctype, MUST be specified as below -->
  40921. <form enctype="multipart/form-data" action="__URL__" method="POST">
  40922.     <!-- MAX_FILE_SIZE must precede the file input field -->
  40923.     <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
  40924.     <!-- Name of input element determines name in $_FILES array -->
  40925.     Send this file: <input name="userfile" type="file" />
  40926.     <input type="submit" value="Send File" />
  40927. </form></PRE
  40928. ></TD
  40929. ></TR
  40930. ></TABLE
  40931. ><P
  40932. >       The <VAR
  40933. CLASS="literal"
  40934. >__URL__</VAR
  40935. > in the above example should be replaced,
  40936.       and point to a PHP file.
  40937.      </P
  40938. ><P
  40939. >       The <VAR
  40940. CLASS="literal"
  40941. >MAX_FILE_SIZE</VAR
  40942. > hidden field (measured in bytes) must
  40943.       precede the file input field, and its value is the maximum filesize accepted.
  40944.       This is an advisory to the browser, PHP also checks it.
  40945.       Fooling this setting on the browser side is quite easy, so never rely
  40946.       on files with a greater size being blocked by this feature.
  40947.       The PHP settings for maximum-size, however, cannot be fooled.
  40948.       This form element should always be used as it
  40949.       saves users the trouble of waiting for a big file being transferred only
  40950.       to find that it was too big and the transfer failed.
  40951.      </P
  40952. ></DIV
  40953. ></TD
  40954. ></TR
  40955. ></TABLE
  40956. >
  40957.    </P
  40958. ><DIV
  40959. CLASS="note"
  40960. ><BLOCKQUOTE
  40961. CLASS="note"
  40962. ><P
  40963. ><B
  40964. >Note: </B
  40965. >
  40966.      Be sure your file upload form has attribute <VAR
  40967. CLASS="literal"
  40968. >enctype="multipart/form-data"</VAR
  40969. >
  40970.      otherwise the file upload will not work.
  40971.     </P
  40972. ></BLOCKQUOTE
  40973. ></DIV
  40974. ><P
  40975. >     The global <A
  40976. HREF="#reserved.variables.files"
  40977. >$_FILES</A
  40978. >
  40979.     exists as of PHP 4.1.0 (Use <VAR
  40980. CLASS="varname"
  40981. >$HTTP_POST_FILES</VAR
  40982. >
  40983.     instead if using an earlier version).
  40984.     These arrays will contain all the uploaded file information.
  40985.    </P
  40986. ><P
  40987. >     The contents of <A
  40988. HREF="#reserved.variables.files"
  40989. >$_FILES</A
  40990. >
  40991.     from the example form is as follows. Note that this assumes the use of 
  40992.     the file upload name <SPAN
  40993. CLASS="emphasis"
  40994. ><I
  40995. CLASS="emphasis"
  40996. >userfile</I
  40997. ></SPAN
  40998. >, as used in the example 
  40999.     script above. This can be any name.
  41000.     <P
  41001. ></P
  41002. ><DIV
  41003. CLASS="variablelist"
  41004. ><DL
  41005. ><DT
  41006. ><VAR
  41007. CLASS="varname"
  41008. >$_FILES['userfile']['name']</VAR
  41009. ></DT
  41010. ><DD
  41011. ><P
  41012. >         The original name of the file on the client machine.
  41013.        </P
  41014. ></DD
  41015. ><DT
  41016. ><VAR
  41017. CLASS="varname"
  41018. >$_FILES['userfile']['type']</VAR
  41019. ></DT
  41020. ><DD
  41021. ><P
  41022. >         The mime type of the file, if the browser provided this
  41023.         information.  An example would be
  41024.         <VAR
  41025. CLASS="literal"
  41026. >"image/gif"</VAR
  41027. >.
  41028.        </P
  41029. ></DD
  41030. ><DT
  41031. ><VAR
  41032. CLASS="varname"
  41033. >$_FILES['userfile']['size']</VAR
  41034. ></DT
  41035. ><DD
  41036. ><P
  41037. >         The size, in bytes, of the uploaded file.
  41038.        </P
  41039. ></DD
  41040. ><DT
  41041. ><VAR
  41042. CLASS="varname"
  41043. >$_FILES['userfile']['tmp_name']</VAR
  41044. ></DT
  41045. ><DD
  41046. ><P
  41047. >         The temporary filename of the file in which the uploaded file
  41048.         was stored on the server.
  41049.        </P
  41050. ></DD
  41051. ><DT
  41052. ><VAR
  41053. CLASS="varname"
  41054. >$_FILES['userfile']['error']</VAR
  41055. ></DT
  41056. ><DD
  41057. ><P
  41058. >         The <A
  41059. HREF="#features.file-upload.errors"
  41060. >error code</A
  41061. >
  41062.         associated with this file upload. This element was added in PHP 4.2.0
  41063.        </P
  41064. ></DD
  41065. ></DL
  41066. ></DIV
  41067. >
  41068.    </P
  41069. ><P
  41070. >     Files will, by default be stored in the server's default temporary
  41071.     directory, unless another location has been given with the <A
  41072. HREF="#ini.upload-tmp-dir"
  41073. >upload_tmp_dir</A
  41074. > directive in
  41075.     <TT
  41076. CLASS="filename"
  41077. >php.ini</TT
  41078. >. The server's default directory can
  41079.     be changed by setting the environment variable
  41080.     <VAR
  41081. CLASS="envar"
  41082. >TMPDIR</VAR
  41083. > in the environment in which PHP runs.
  41084.     Setting it using <A
  41085. HREF="#function.putenv"
  41086. ><B
  41087. CLASS="function"
  41088. >putenv()</B
  41089. ></A
  41090. > from within a PHP
  41091.     script will not work. This environment variable can also be used
  41092.     to make sure that other operations are working on uploaded files,
  41093.     as well.
  41094.     <TABLE
  41095. WIDTH="100%"
  41096. BORDER="0"
  41097. CELLPADDING="0"
  41098. CELLSPACING="0"
  41099. CLASS="EXAMPLE"
  41100. ><TR
  41101. ><TD
  41102. ><DIV
  41103. CLASS="example"
  41104. ><A
  41105. NAME="AEN6680"
  41106. ></A
  41107. ><P
  41108. ><B
  41109. >Example 38-2. Validating file uploads</B
  41110. ></P
  41111. ><P
  41112. >       See also the function entries for <A
  41113. HREF="#function.is-uploaded-file"
  41114. ><B
  41115. CLASS="function"
  41116. >is_uploaded_file()</B
  41117. ></A
  41118. > 
  41119.       and <A
  41120. HREF="#function.move-uploaded-file"
  41121. ><B
  41122. CLASS="function"
  41123. >move_uploaded_file()</B
  41124. ></A
  41125. > for further information. The
  41126.       following example will process the file upload that came from a form.
  41127.      </P
  41128. ><TABLE
  41129. BORDER="0"
  41130. BGCOLOR="#E0E0E0"
  41131. CELLPADDING="5"
  41132. ><TR
  41133. ><TD
  41134. ><PRE
  41135. CLASS="php"
  41136. ><?php
  41137. // In PHP versions earlier than 4.1.0, $HTTP_POST_FILES should be used instead
  41138. // of $_FILES.
  41139.  
  41140. $uploaddir = '/var/www/uploads/';
  41141. $uploadfile = $uploaddir . basename($_FILES['userfile']['name']);
  41142.  
  41143. echo '<pre>';
  41144. if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
  41145.     echo "File is valid, and was successfully uploaded.\n";
  41146. } else {
  41147.     echo "Possible file upload attack!\n";
  41148. }
  41149.  
  41150. echo 'Here is some more debugging info:';
  41151. print_r($_FILES);
  41152.  
  41153. print "</pre>";
  41154.  
  41155. ?></PRE
  41156. ></TD
  41157. ></TR
  41158. ></TABLE
  41159. ></DIV
  41160. ></TD
  41161. ></TR
  41162. ></TABLE
  41163. >
  41164.    </P
  41165. ><P
  41166. >     The PHP script which receives the uploaded file should implement
  41167.     whatever logic is necessary for determining what should be done
  41168.     with the uploaded file. You can, for example, use the
  41169.     <VAR
  41170. CLASS="varname"
  41171. >$_FILES['userfile']['size']</VAR
  41172. > variable
  41173.     to throw away any files that are either too small or too big.  You
  41174.     could use the
  41175.     <VAR
  41176. CLASS="varname"
  41177. >$_FILES['userfile']['type']</VAR
  41178. > variable
  41179.     to throw away any files that didn't match a certain type criteria.
  41180.     As of PHP 4.2.0, you could use <VAR
  41181. CLASS="varname"
  41182. >$_FILES['userfile']['error']</VAR
  41183. > 
  41184.     and plan your logic according to the <A
  41185. HREF="#features.file-upload.errors"
  41186. >error codes</A
  41187. >.
  41188.     Whatever the logic, you should either delete the file from the
  41189.     temporary directory or move it elsewhere.
  41190.    </P
  41191. ><P
  41192. >     If no file is selected for upload in your form, PHP will return
  41193.     <VAR
  41194. CLASS="varname"
  41195. >$_FILES['userfile']['size']</VAR
  41196. > as 0, and
  41197.     <VAR
  41198. CLASS="varname"
  41199. >$_FILES['userfile']['tmp_name']</VAR
  41200. > as none.
  41201.    </P
  41202. ><P
  41203. >     The file will be deleted from the temporary directory at the end
  41204.     of the request if it has not been moved away or renamed.
  41205.    </P
  41206. ></DIV
  41207. ><DIV
  41208. CLASS="sect1"
  41209. ><HR><H2
  41210. CLASS="sect1"
  41211. ><A
  41212. NAME="features.file-upload.errors"
  41213. >Error Messages Explained</A
  41214. ></H2
  41215. ><P
  41216. >     Since PHP 4.2.0, PHP returns an appropriate error code along with the 
  41217.     file array.  The error code can be found in the 
  41218.     <VAR
  41219. CLASS="literal"
  41220. >error</VAR
  41221. > segment of the file array that is created 
  41222.     during the file upload by PHP. In other words, the error might be 
  41223.     found in <VAR
  41224. CLASS="varname"
  41225. >$_FILES['userfile']['error']</VAR
  41226. >.
  41227.    </P
  41228. ><P
  41229. >     <P
  41230. ></P
  41231. ><DIV
  41232. CLASS="variablelist"
  41233. ><DL
  41234. ><DT
  41235. ><TT
  41236. CLASS="constant"
  41237. ><B
  41238. >UPLOAD_ERR_OK</B
  41239. ></TT
  41240. ></DT
  41241. ><DD
  41242. ><P
  41243. >         Value: 0; There is no error, the file uploaded with success.
  41244.        </P
  41245. ></DD
  41246. ><DT
  41247. ><TT
  41248. CLASS="constant"
  41249. ><B
  41250. >UPLOAD_ERR_INI_SIZE</B
  41251. ></TT
  41252. ></DT
  41253. ><DD
  41254. ><P
  41255. >         Value: 1; The uploaded file exceeds the
  41256.         <A
  41257. HREF="#ini.upload-max-filesize"
  41258. >upload_max_filesize</A
  41259. > 
  41260.         directive in <TT
  41261. CLASS="filename"
  41262. >php.ini</TT
  41263. >.
  41264.        </P
  41265. ></DD
  41266. ><DT
  41267. ><TT
  41268. CLASS="constant"
  41269. ><B
  41270. >UPLOAD_ERR_FORM_SIZE</B
  41271. ></TT
  41272. ></DT
  41273. ><DD
  41274. ><P
  41275. >         Value: 2; The uploaded file exceeds the <SPAN
  41276. CLASS="emphasis"
  41277. ><I
  41278. CLASS="emphasis"
  41279. >MAX_FILE_SIZE</I
  41280. ></SPAN
  41281. > 
  41282.         directive that was specified in the HTML form.
  41283.        </P
  41284. ></DD
  41285. ><DT
  41286. ><TT
  41287. CLASS="constant"
  41288. ><B
  41289. >UPLOAD_ERR_PARTIAL</B
  41290. ></TT
  41291. ></DT
  41292. ><DD
  41293. ><P
  41294. >         Value: 3; The uploaded file was only partially uploaded.
  41295.        </P
  41296. ></DD
  41297. ><DT
  41298. ><TT
  41299. CLASS="constant"
  41300. ><B
  41301. >UPLOAD_ERR_NO_FILE</B
  41302. ></TT
  41303. ></DT
  41304. ><DD
  41305. ><P
  41306. >         Value: 4; No file was uploaded.
  41307.        </P
  41308. ></DD
  41309. ><DT
  41310. ><TT
  41311. CLASS="constant"
  41312. ><B
  41313. >UPLOAD_ERR_NO_TMP_DIR</B
  41314. ></TT
  41315. ></DT
  41316. ><DD
  41317. ><P
  41318. >         Value: 6; Missing a temporary folder. Introduced in PHP 4.3.10 and PHP
  41319.         5.0.3.
  41320.        </P
  41321. ></DD
  41322. ></DL
  41323. ></DIV
  41324. >
  41325.    </P
  41326. ><DIV
  41327. CLASS="note"
  41328. ><BLOCKQUOTE
  41329. CLASS="note"
  41330. ><P
  41331. ><B
  41332. >Note: </B
  41333. >
  41334.      These became PHP constants in PHP 4.3.0.
  41335.     </P
  41336. ></BLOCKQUOTE
  41337. ></DIV
  41338. ></DIV
  41339. ><DIV
  41340. CLASS="sect1"
  41341. ><HR><H2
  41342. CLASS="sect1"
  41343. ><A
  41344. NAME="features.file-upload.common-pitfalls"
  41345. >Common Pitfalls</A
  41346. ></H2
  41347. ><P
  41348. >     The <VAR
  41349. CLASS="literal"
  41350. >MAX_FILE_SIZE</VAR
  41351. > item cannot specify a file size 
  41352.     greater than the file size that has been set in the <A
  41353. HREF="#ini.upload-max-filesize"
  41354. >upload_max_filesize</A
  41355. > ini-setting.
  41356.     The default is 2 Megabytes.
  41357.    </P
  41358. ><P
  41359. >     If a memory limit is enabled, a larger <A
  41360. HREF="#ini.memory-limit"
  41361. >memory_limit</A
  41362. > may be needed. Make
  41363.     sure you set <A
  41364. HREF="#ini.memory-limit"
  41365. >memory_limit</A
  41366. >
  41367.     large enough.
  41368.    </P
  41369. ><P
  41370. >     If <A
  41371. HREF="#ini.max-execution-time"
  41372. >max_execution_time</A
  41373. >
  41374.     is set too small, script execution may be exceeded by the value. Make
  41375.     sure you set <VAR
  41376. CLASS="literal"
  41377. >max_execution_time</VAR
  41378. > large enough.
  41379.    </P
  41380. ><DIV
  41381. CLASS="note"
  41382. ><BLOCKQUOTE
  41383. CLASS="note"
  41384. ><P
  41385. ><B
  41386. >Note: </B
  41387. >
  41388.      <A
  41389. HREF="#ini.max-execution-time"
  41390. >max_execution_time</A
  41391. > only
  41392.      affects the execution time of the script itself.  Any time spent
  41393.      on activity that happens outside the execution of the script
  41394.      such as system calls using <A
  41395. HREF="#function.system"
  41396. ><B
  41397. CLASS="function"
  41398. >system()</B
  41399. ></A
  41400. >, the
  41401.      <A
  41402. HREF="#function.sleep"
  41403. ><B
  41404. CLASS="function"
  41405. >sleep()</B
  41406. ></A
  41407. > function, database queries, time taken by
  41408.      the file upload process, etc. is not included when determining the maximum
  41409.      time that the script has been running.
  41410.     </P
  41411. ></BLOCKQUOTE
  41412. ></DIV
  41413. ><DIV
  41414. CLASS="warning"
  41415. ><P
  41416. ></P
  41417. ><TABLE
  41418. CLASS="warning"
  41419. BORDER="1"
  41420. WIDTH="100%"
  41421. ><TR
  41422. ><TD
  41423. ALIGN="CENTER"
  41424. ><B
  41425. >Warning</B
  41426. ></TD
  41427. ></TR
  41428. ><TR
  41429. ><TD
  41430. ALIGN="LEFT"
  41431. ><P
  41432. >      <A
  41433. HREF="#ini.max-input-time"
  41434. >max_input_time</A
  41435. > sets the maximum
  41436.      time, in seconds, the script is allowed to receive input; this includes
  41437.      file uploads.  For large or multiple files, or users on slower connections,
  41438.      the default of <VAR
  41439. CLASS="literal"
  41440. >60 seconds</VAR
  41441. > may be exceeded.
  41442.     </P
  41443. ></TD
  41444. ></TR
  41445. ></TABLE
  41446. ></DIV
  41447. ><P
  41448. >     If <A
  41449. HREF="#ini.post-max-size"
  41450. >post_max_size</A
  41451. > is set too
  41452.     small, large files cannot be uploaded.  Make sure you set
  41453.     <VAR
  41454. CLASS="literal"
  41455. >post_max_size</VAR
  41456. > large enough.
  41457.    </P
  41458. ><P
  41459. >     Not validating which file you operate on may mean that users can access
  41460.     sensitive information in other directories.
  41461.    </P
  41462. ><P
  41463. >     Please note that the <SPAN
  41464. CLASS="productname"
  41465. >CERN httpd</SPAN
  41466. > seems to strip off everything
  41467.     starting at the first whitespace in the content-type mime header
  41468.     it gets from the client.  As long as this is the case, <SPAN
  41469. CLASS="productname"
  41470. >CERN httpd</SPAN
  41471. >
  41472.     will not support the file upload feature.
  41473.    </P
  41474. ><P
  41475. >     Due to the large amount of directory listing styles we cannot guarantee
  41476.     that files with exotic names (like containing spaces) are handled properly.
  41477.    </P
  41478. ><P
  41479. >     A developer may not mix normal input fields and file upload fields in the same
  41480.     form variable (by using an input name like <VAR
  41481. CLASS="literal"
  41482. >foo[]</VAR
  41483. >).
  41484.    </P
  41485. ></DIV
  41486. ><DIV
  41487. CLASS="sect1"
  41488. ><HR><H2
  41489. CLASS="sect1"
  41490. ><A
  41491. NAME="features.file-upload.multiple"
  41492. >Uploading multiple files</A
  41493. ></H2
  41494. ><P
  41495. >     Multiple files can be uploaded using different
  41496.     <VAR
  41497. CLASS="literal"
  41498. >name</VAR
  41499. > for <VAR
  41500. CLASS="literal"
  41501. >input</VAR
  41502. >.
  41503.    </P
  41504. ><P
  41505. >     It is also possible to upload multiple files simultaneously and
  41506.     have the information organized automatically in arrays for you. To
  41507.     do so, you need to use the same array submission syntax in the
  41508.     HTML form as you do with multiple selects and checkboxes:
  41509.    </P
  41510. ><DIV
  41511. CLASS="note"
  41512. ><BLOCKQUOTE
  41513. CLASS="note"
  41514. ><P
  41515. ><B
  41516. >Note: </B
  41517. >
  41518.      Support for multiple file uploads was added in PHP 3.0.10.
  41519.     </P
  41520. ></BLOCKQUOTE
  41521. ></DIV
  41522. ><P
  41523. >     <TABLE
  41524. WIDTH="100%"
  41525. BORDER="0"
  41526. CELLPADDING="0"
  41527. CELLSPACING="0"
  41528. CLASS="EXAMPLE"
  41529. ><TR
  41530. ><TD
  41531. ><DIV
  41532. CLASS="example"
  41533. ><A
  41534. NAME="AEN6776"
  41535. ></A
  41536. ><P
  41537. ><B
  41538. >Example 38-3. Uploading multiple files</B
  41539. ></P
  41540. ><TABLE
  41541. BORDER="0"
  41542. BGCOLOR="#E0E0E0"
  41543. CELLPADDING="5"
  41544. ><TR
  41545. ><TD
  41546. ><PRE
  41547. CLASS="html"
  41548. ><form action="file-upload.php" method="post" enctype="multipart/form-data">
  41549.   Send these files:<br />
  41550.   <input name="userfile[]" type="file" /><br />
  41551.   <input name="userfile[]" type="file" /><br />
  41552.   <input type="submit" value="Send files" />
  41553. </form></PRE
  41554. ></TD
  41555. ></TR
  41556. ></TABLE
  41557. ></DIV
  41558. ></TD
  41559. ></TR
  41560. ></TABLE
  41561. >
  41562.    </P
  41563. ><P
  41564. >     When the above form is submitted, the arrays
  41565.     <VAR
  41566. CLASS="varname"
  41567. >$_FILES['userfile']</VAR
  41568. >,
  41569.     <VAR
  41570. CLASS="varname"
  41571. >$_FILES['userfile']['name']</VAR
  41572. >, and
  41573.     <VAR
  41574. CLASS="varname"
  41575. >$_FILES['userfile']['size']</VAR
  41576. > will be
  41577.     initialized (as well as in <VAR
  41578. CLASS="varname"
  41579. >$HTTP_POST_FILES</VAR
  41580. > for PHP versions prior
  41581.     to 4.1.0).
  41582.     When
  41583.     <A
  41584. HREF="#ini.register-globals"
  41585. >register_globals</A
  41586. > is on, globals for uploaded
  41587.     files are also initialized. Each of these will be a numerically
  41588.     indexed array of the appropriate values for the submitted files.
  41589.    </P
  41590. ><P
  41591. >     For instance, assume that the filenames
  41592.     <TT
  41593. CLASS="filename"
  41594. >/home/test/review.html</TT
  41595. > and
  41596.     <TT
  41597. CLASS="filename"
  41598. >/home/test/xwp.out</TT
  41599. > are submitted.  In this
  41600.     case, <VAR
  41601. CLASS="varname"
  41602. >$_FILES['userfile']['name'][0]</VAR
  41603. >
  41604.     would contain the value <TT
  41605. CLASS="filename"
  41606. >review.html</TT
  41607. >, and
  41608.     <VAR
  41609. CLASS="varname"
  41610. >$_FILES['userfile']['name'][1]</VAR
  41611. > would
  41612.     contain the value <TT
  41613. CLASS="filename"
  41614. >xwp.out</TT
  41615. >. Similarly,
  41616.     <VAR
  41617. CLASS="varname"
  41618. >$_FILES['userfile']['size'][0]</VAR
  41619. > would
  41620.     contain <TT
  41621. CLASS="filename"
  41622. >review.html</TT
  41623. >'s file size, and so forth.
  41624.    </P
  41625. ><P
  41626. >     <VAR
  41627. CLASS="varname"
  41628. >$_FILES['userfile']['name'][0]</VAR
  41629. >,
  41630.     <VAR
  41631. CLASS="varname"
  41632. >$_FILES['userfile']['tmp_name'][0]</VAR
  41633. >,
  41634.     <VAR
  41635. CLASS="varname"
  41636. >$_FILES['userfile']['size'][0]</VAR
  41637. >, and
  41638.     <VAR
  41639. CLASS="varname"
  41640. >$_FILES['userfile']['type'][0]</VAR
  41641. > are
  41642.     also set.
  41643.    </P
  41644. ></DIV
  41645. ><DIV
  41646. CLASS="sect1"
  41647. ><HR><H2
  41648. CLASS="sect1"
  41649. ><A
  41650. NAME="features.file-upload.put-method"
  41651. >PUT method support</A
  41652. ></H2
  41653. ><P
  41654. >     PUT method support has changed between PHP 3 and PHP 4.
  41655.     In PHP 4, one should use the standard input stream to read
  41656.     the contents of an HTTP PUT.
  41657.    </P
  41658. ><P
  41659. >     <TABLE
  41660. WIDTH="100%"
  41661. BORDER="0"
  41662. CELLPADDING="0"
  41663. CELLSPACING="0"
  41664. CLASS="EXAMPLE"
  41665. ><TR
  41666. ><TD
  41667. ><DIV
  41668. CLASS="example"
  41669. ><A
  41670. NAME="AEN6803"
  41671. ></A
  41672. ><P
  41673. ><B
  41674. >Example 38-4. Saving HTTP PUT files with PHP 4</B
  41675. ></P
  41676. ><TABLE
  41677. BORDER="0"
  41678. BGCOLOR="#E0E0E0"
  41679. CELLPADDING="5"
  41680. ><TR
  41681. ><TD
  41682. ><PRE
  41683. CLASS="php"
  41684. ><?php
  41685. /* PUT data comes in on the stdin stream */
  41686. $putdata = fopen("php://stdin", "r");
  41687.  
  41688. /* Open a file for writing */
  41689. $fp = fopen("myputfile.ext", "w");
  41690.  
  41691. /* Read the data 1 KB at a time
  41692.    and write to the file */
  41693. while ($data = fread($putdata, 1024))
  41694.   fwrite($fp, $data);
  41695.  
  41696. /* Close the streams */
  41697. fclose($fp);
  41698. fclose($putdata);
  41699. ?></PRE
  41700. ></TD
  41701. ></TR
  41702. ></TABLE
  41703. ></DIV
  41704. ></TD
  41705. ></TR
  41706. ></TABLE
  41707. >
  41708.    </P
  41709. ><DIV
  41710. CLASS="note"
  41711. ><BLOCKQUOTE
  41712. CLASS="note"
  41713. ><P
  41714. ><B
  41715. >Note: </B
  41716. >
  41717.      All documentation below applies to PHP 3 only.
  41718.     </P
  41719. ></BLOCKQUOTE
  41720. ></DIV
  41721. ><P
  41722. >     PHP provides support for the HTTP PUT method used by clients such
  41723.     as <SPAN
  41724. CLASS="productname"
  41725. >Netscape Composer</SPAN
  41726. > and W3C <SPAN
  41727. CLASS="productname"
  41728. >Amaya</SPAN
  41729. >.  
  41730.     PUT requests are much simpler
  41731.     than a file upload and they look something like this:
  41732.     <DIV
  41733. CLASS="informalexample"
  41734. ><P
  41735. ></P
  41736. ><A
  41737. NAME="AEN6811"
  41738. ></A
  41739. ><TABLE
  41740. BORDER="0"
  41741. BGCOLOR="#E0E0E0"
  41742. CELLPADDING="5"
  41743. ><TR
  41744. ><TD
  41745. ><PRE
  41746. CLASS="programlisting"
  41747. >PUT /path/filename.html HTTP/1.1</PRE
  41748. ></TD
  41749. ></TR
  41750. ></TABLE
  41751. ><P
  41752. ></P
  41753. ></DIV
  41754. >
  41755.    </P
  41756. ><P
  41757. >     This would normally mean that the remote client would like to save
  41758.     the content that follows as: <TT
  41759. CLASS="filename"
  41760. >/path/filename.html</TT
  41761. > in your web tree.
  41762.     It is obviously not a good idea for Apache or PHP to automatically
  41763.     let everybody overwrite any files in your web tree.  So, to handle
  41764.     such a request you have to first tell your web server that you
  41765.     want a certain PHP script to handle the request.  In Apache you do
  41766.     this with the <SPAN
  41767. CLASS="emphasis"
  41768. ><I
  41769. CLASS="emphasis"
  41770. >Script</I
  41771. ></SPAN
  41772. > directive.  It can be
  41773.     placed almost anywhere in your Apache configuration file.  A
  41774.     common place is inside a <Directory> block or perhaps inside
  41775.     a <Virtualhost> block.  A line like this would do the trick:
  41776.     <DIV
  41777. CLASS="informalexample"
  41778. ><P
  41779. ></P
  41780. ><A
  41781. NAME="AEN6816"
  41782. ></A
  41783. ><TABLE
  41784. BORDER="0"
  41785. BGCOLOR="#E0E0E0"
  41786. CELLPADDING="5"
  41787. ><TR
  41788. ><TD
  41789. ><PRE
  41790. CLASS="programlisting"
  41791. >Script PUT /put.php</PRE
  41792. ></TD
  41793. ></TR
  41794. ></TABLE
  41795. ><P
  41796. ></P
  41797. ></DIV
  41798. >
  41799.    </P
  41800. ><P
  41801. >     This tells Apache to send all PUT requests for URIs that match the
  41802.     context in which you put this line to the put.php script.  This
  41803.     assumes, of course, that you have PHP enabled for the .php
  41804.     extension and PHP is active.
  41805.    </P
  41806. ><P
  41807. >     Inside your put.php file you would then do something like this:
  41808.    </P
  41809. ><P
  41810. >     <DIV
  41811. CLASS="informalexample"
  41812. ><P
  41813. ></P
  41814. ><A
  41815. NAME="AEN6821"
  41816. ></A
  41817. ><TABLE
  41818. BORDER="0"
  41819. BGCOLOR="#E0E0E0"
  41820. CELLPADDING="5"
  41821. ><TR
  41822. ><TD
  41823. ><PRE
  41824. CLASS="php"
  41825. ><?php copy($PHP_UPLOADED_FILE_NAME, $DOCUMENT_ROOT . $REQUEST_URI); ?></PRE
  41826. ></TD
  41827. ></TR
  41828. ></TABLE
  41829. ><P
  41830. ></P
  41831. ></DIV
  41832. >
  41833.    </P
  41834. ><P
  41835. >     This would copy the file to the location requested by the remote
  41836.     client.  You would probably want to perform some checks and/or
  41837.     authenticate the user before performing this file copy.  The only
  41838.     trick here is that when PHP sees a PUT-method request it stores
  41839.     the uploaded file in a temporary file just like those handled by
  41840.     the <A
  41841. HREF="#features.file-upload.post-method"
  41842. >POST-method</A
  41843. >.
  41844.     When the request ends, this temporary file is deleted.  So, your
  41845.     PUT handling PHP script has to copy that file somewhere.  The
  41846.     filename of this temporary file is in the <VAR
  41847. CLASS="varname"
  41848. >$PHP_PUT_FILENAME</VAR
  41849. >
  41850.     variable, and you can see the suggested destination filename in
  41851.     the <VAR
  41852. CLASS="varname"
  41853. >$REQUEST_URI</VAR
  41854. > (may vary on non-Apache web servers).  This
  41855.     destination filename is the one that the remote client specified.
  41856.     You do not have to listen to this client.  You could, for example,
  41857.     copy all uploaded files to a special uploads directory.
  41858.    </P
  41859. ></DIV
  41860. ></DIV
  41861. ><DIV
  41862. CLASS="chapter"
  41863. ><HR><H1
  41864. ><A
  41865. NAME="features.remote-files"
  41866. >Chapter 39. Using remote files</A
  41867. ></H1
  41868. ><P
  41869. >    As long as <VAR
  41870. CLASS="option"
  41871. >allow_url_fopen</VAR
  41872. > is enabled in
  41873.    <TT
  41874. CLASS="filename"
  41875. >php.ini</TT
  41876. >, you can use <ACRONYM
  41877. CLASS="acronym"
  41878. >HTTP</ACRONYM
  41879. > and <ACRONYM
  41880. CLASS="acronym"
  41881. >FTP</ACRONYM
  41882. > 
  41883.    URLs with most of the functions
  41884.    that take a filename as a parameter.  In addition, URLs can be
  41885.    used with the <A
  41886. HREF="#function.include"
  41887. ><B
  41888. CLASS="function"
  41889. >include()</B
  41890. ></A
  41891. >,
  41892.    <A
  41893. HREF="#function.include-once"
  41894. ><B
  41895. CLASS="function"
  41896. >include_once()</B
  41897. ></A
  41898. >, <A
  41899. HREF="#function.require"
  41900. ><B
  41901. CLASS="function"
  41902. >require()</B
  41903. ></A
  41904. > and
  41905.    <A
  41906. HREF="#function.require-once"
  41907. ><B
  41908. CLASS="function"
  41909. >require_once()</B
  41910. ></A
  41911. > statements.
  41912.    See <A
  41913. HREF="#wrappers"
  41914. >Appendix L</A
  41915. > for more information about the protocols
  41916.    supported by PHP.
  41917.   </P
  41918. ><DIV
  41919. CLASS="note"
  41920. ><BLOCKQUOTE
  41921. CLASS="note"
  41922. ><P
  41923. ><B
  41924. >Note: </B
  41925. >
  41926.    In PHP 4.0.3 and older, in order to use URL wrappers, you were required
  41927.    to configure PHP using the configure option
  41928.    <VAR
  41929. CLASS="option"
  41930. >--enable-url-fopen-wrapper</VAR
  41931. >.
  41932.    </P
  41933. ></BLOCKQUOTE
  41934. ></DIV
  41935. ><P
  41936. >    <DIV
  41937. CLASS="note"
  41938. ><BLOCKQUOTE
  41939. CLASS="note"
  41940. ><P
  41941. ><B
  41942. >Note: </B
  41943. >
  41944.      The Windows versions of PHP earlier than PHP 4.3
  41945.      did not support remote file accessing for the following functions:
  41946.      <A
  41947. HREF="#function.include"
  41948. ><B
  41949. CLASS="function"
  41950. >include()</B
  41951. ></A
  41952. >, <A
  41953. HREF="#function.include-once"
  41954. ><B
  41955. CLASS="function"
  41956. >include_once()</B
  41957. ></A
  41958. >,
  41959.      <A
  41960. HREF="#function.require"
  41961. ><B
  41962. CLASS="function"
  41963. >require()</B
  41964. ></A
  41965. >, <A
  41966. HREF="#function.require-once"
  41967. ><B
  41968. CLASS="function"
  41969. >require_once()</B
  41970. ></A
  41971. >,
  41972.      and the imagecreatefromXXX functions in the <A
  41973. HREF="#ref.image"
  41974. >Reference XLVI, <I
  41975. >Image Functions</I
  41976. ></A
  41977. >
  41978.      extension.
  41979.     </P
  41980. ></BLOCKQUOTE
  41981. ></DIV
  41982. >
  41983.   </P
  41984. ><P
  41985. >    For example, you can use this to open a file on a remote web server,
  41986.    parse the output for the data you want, and then use that data in a
  41987.    database query, or simply to output it in a style matching the rest
  41988.    of your website.
  41989.   </P
  41990. ><P
  41991. >    <TABLE
  41992. WIDTH="100%"
  41993. BORDER="0"
  41994. CELLPADDING="0"
  41995. CELLSPACING="0"
  41996. CLASS="EXAMPLE"
  41997. ><TR
  41998. ><TD
  41999. ><DIV
  42000. CLASS="example"
  42001. ><A
  42002. NAME="AEN6852"
  42003. ></A
  42004. ><P
  42005. ><B
  42006. >Example 39-1. Getting the title of a remote page</B
  42007. ></P
  42008. ><TABLE
  42009. BORDER="0"
  42010. BGCOLOR="#E0E0E0"
  42011. CELLPADDING="5"
  42012. ><TR
  42013. ><TD
  42014. ><PRE
  42015. CLASS="php"
  42016. ><?php
  42017. $file = fopen ("http://www.example.com/", "r");
  42018. if (!$file) {
  42019.     echo "<p>Unable to open remote file.\n";
  42020.     exit;
  42021. }
  42022. while (!feof ($file)) {
  42023.     $line = fgets ($file, 1024);
  42024.     /* This only works if the title and its tags are on one line */
  42025.     if (eregi ("<title>(.*)</title>", $line, $out)) {
  42026.         $title = $out[1];
  42027.         break;
  42028.     }
  42029. }
  42030. fclose($file);
  42031. ?></PRE
  42032. ></TD
  42033. ></TR
  42034. ></TABLE
  42035. ></DIV
  42036. ></TD
  42037. ></TR
  42038. ></TABLE
  42039. >
  42040.   </P
  42041. ><P
  42042. >    You can also write to files on an FTP server (provided that you
  42043.    have connected as a user with the correct access rights). You
  42044.    can only create new files using this method; if you try to overwrite
  42045.    a file that already exists, the <A
  42046. HREF="#function.fopen"
  42047. ><B
  42048. CLASS="function"
  42049. >fopen()</B
  42050. ></A
  42051. > call will
  42052.    fail.
  42053.   </P
  42054. ><P
  42055. >    To connect as a user other than 'anonymous', you need to specify
  42056.    the username (and possibly password) within the URL, such as
  42057.    'ftp://user:password@ftp.example.com/path/to/file'. (You can use the
  42058.    same sort of syntax to access files via HTTP when they require Basic
  42059.    authentication.)
  42060.   </P
  42061. ><P
  42062. >    <TABLE
  42063. WIDTH="100%"
  42064. BORDER="0"
  42065. CELLPADDING="0"
  42066. CELLSPACING="0"
  42067. CLASS="EXAMPLE"
  42068. ><TR
  42069. ><TD
  42070. ><DIV
  42071. CLASS="example"
  42072. ><A
  42073. NAME="AEN6859"
  42074. ></A
  42075. ><P
  42076. ><B
  42077. >Example 39-2. Storing data on a remote server</B
  42078. ></P
  42079. ><TABLE
  42080. BORDER="0"
  42081. BGCOLOR="#E0E0E0"
  42082. CELLPADDING="5"
  42083. ><TR
  42084. ><TD
  42085. ><PRE
  42086. CLASS="php"
  42087. ><?php
  42088. $file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
  42089. if (!$file) {
  42090.     echo "<p>Unable to open remote file for writing.\n";
  42091.     exit;
  42092. }
  42093. /* Write the data here. */
  42094. fwrite ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
  42095. fclose ($file);
  42096. ?></PRE
  42097. ></TD
  42098. ></TR
  42099. ></TABLE
  42100. ></DIV
  42101. ></TD
  42102. ></TR
  42103. ></TABLE
  42104. >
  42105.   </P
  42106. ><P
  42107. >    <DIV
  42108. CLASS="note"
  42109. ><BLOCKQUOTE
  42110. CLASS="note"
  42111. ><P
  42112. ><B
  42113. >Note: </B
  42114. >
  42115.      You might get the idea from the example above that you can use
  42116.      this technique to write to a remote log file. Unfortunately
  42117.      that would not work because the <A
  42118. HREF="#function.fopen"
  42119. ><B
  42120. CLASS="function"
  42121. >fopen()</B
  42122. ></A
  42123. > call will
  42124.      fail if the remote file already exists. To do distributed logging
  42125.      like that, you should take a look at <A
  42126. HREF="#function.syslog"
  42127. ><B
  42128. CLASS="function"
  42129. >syslog()</B
  42130. ></A
  42131. >.
  42132.     </P
  42133. ></BLOCKQUOTE
  42134. ></DIV
  42135. >
  42136.   </P
  42137. ></DIV
  42138. ><DIV
  42139. CLASS="chapter"
  42140. ><HR><H1
  42141. ><A
  42142. NAME="features.connection-handling"
  42143. >Chapter 40. Connection handling</A
  42144. ></H1
  42145. ><DIV
  42146. CLASS="note"
  42147. ><BLOCKQUOTE
  42148. CLASS="note"
  42149. ><P
  42150. ><B
  42151. >Note: </B
  42152. >The following applies to 3.0.7 and later.</P
  42153. ></BLOCKQUOTE
  42154. ></DIV
  42155. ><P
  42156. >    Internally in PHP a connection status is maintained.  There are 3
  42157.    possible states:
  42158.    <P
  42159. ></P
  42160. ><UL
  42161. ><LI
  42162. ><P
  42163. >0 - NORMAL</P
  42164. ></LI
  42165. ><LI
  42166. ><P
  42167. >1 - ABORTED</P
  42168. ></LI
  42169. ><LI
  42170. ><P
  42171. >2 - TIMEOUT</P
  42172. ></LI
  42173. ></UL
  42174. >
  42175.   </P
  42176. ><P
  42177. >    When a PHP script is running normally the NORMAL state, is active.
  42178.    If the remote client disconnects the ABORTED state flag is
  42179.    turned on.  A remote client disconnect is usually caused by the
  42180.    user hitting his STOP button.  If the PHP-imposed time limit (see
  42181.    <A
  42182. HREF="#function.set-time-limit"
  42183. ><B
  42184. CLASS="function"
  42185. >set_time_limit()</B
  42186. ></A
  42187. >) is hit, the TIMEOUT state flag
  42188.    is turned on.</P
  42189. ><P
  42190. >    You can decide whether or not you want a client disconnect to cause
  42191.    your script to be aborted.  Sometimes it is handy to always have your
  42192.    scripts run to completion even if there is no remote browser receiving
  42193.    the output.  The default behaviour is however for your script to be
  42194.    aborted when the remote client disconnects.  This behaviour can be
  42195.    set via the ignore_user_abort <TT
  42196. CLASS="filename"
  42197. >php.ini</TT
  42198. > directive as well as through
  42199.    the corresponding "php_value ignore_user_abort" Apache .conf directive or
  42200.    with the <A
  42201. HREF="#function.ignore-user-abort"
  42202. ><B
  42203. CLASS="function"
  42204. >ignore_user_abort()</B
  42205. ></A
  42206. > function.  If you do
  42207.    not tell PHP to ignore a user abort and the user aborts, your script
  42208.    will terminate.  The one exception is if you have registered a shutdown
  42209.    function using <A
  42210. HREF="#function.register-shutdown-function"
  42211. ><B
  42212. CLASS="function"
  42213. >register_shutdown_function()</B
  42214. ></A
  42215. >.  With a
  42216.    shutdown function, when the remote user hits his STOP button, the
  42217.    next time your script tries to output something PHP will detect that
  42218.    the connection has been aborted and the shutdown function is called.
  42219.    This shutdown function will also get called at the end of your script
  42220.    terminating normally, so to do something different in case of a client
  42221.    disconnect you can use the <A
  42222. HREF="#function.connection-aborted"
  42223. ><B
  42224. CLASS="function"
  42225. >connection_aborted()</B
  42226. ></A
  42227. >
  42228.    function.  This function will return <TT
  42229. CLASS="constant"
  42230. ><B
  42231. >TRUE</B
  42232. ></TT
  42233. > if the connection was
  42234.    aborted.</P
  42235. ><P
  42236. >    Your script can also be terminated by the built-in script timer.
  42237.    The default timeout is 30 seconds.  It can be changed using
  42238.    the <VAR
  42239. CLASS="option"
  42240. >max_execution_time</VAR
  42241. > <TT
  42242. CLASS="filename"
  42243. >php.ini</TT
  42244. > directive or the corresponding
  42245.    <VAR
  42246. CLASS="literal"
  42247. >php_value max_execution_time</VAR
  42248. > Apache .conf directive as well as with
  42249.    the <A
  42250. HREF="#function.set-time-limit"
  42251. ><B
  42252. CLASS="function"
  42253. >set_time_limit()</B
  42254. ></A
  42255. > function.  When the timer
  42256.    expires the script will be aborted and as with the above client
  42257.    disconnect case, if a shutdown function has been registered it will
  42258.    be called.  Within this shutdown function you can check to see if
  42259.    a timeout caused the shutdown function to be called by calling the
  42260.    <A
  42261. HREF="#function.connection-status"
  42262. ><B
  42263. CLASS="function"
  42264. >connection_status()</B
  42265. ></A
  42266. > function.  This function will
  42267.    return 2 if a timeout caused the shutdown function to be called.
  42268.   </P
  42269. ><P
  42270. >    One thing to note is that both the ABORTED and the TIMEOUT states
  42271.    can be active at the same time.  This is possible if you tell
  42272.    PHP to ignore user aborts.  PHP will still note the fact that
  42273.    a user may have broken the connection, but the script will keep
  42274.    running.  If it then hits the time limit it will be aborted and
  42275.    your shutdown function, if any, will be called.  At this point
  42276.    you will find that <A
  42277. HREF="#function.connection-status"
  42278. ><B
  42279. CLASS="function"
  42280. >connection_status()</B
  42281. ></A
  42282. >
  42283.    returns 3.
  42284.   </P
  42285. ></DIV
  42286. ><DIV
  42287. CLASS="chapter"
  42288. ><HR><H1
  42289. ><A
  42290. NAME="features.persistent-connections"
  42291. >Chapter 41. Persistent Database Connections</A
  42292. ></H1
  42293. ><P
  42294. >    Persistent connections are links that do not close when the
  42295.    execution of your script ends. When a persistent connection is
  42296.    requested, PHP checks if there's already an identical persistent
  42297.    connection (that remained open from earlier) - and if it exists, it
  42298.    uses it. If it does not exist, it creates the link. An 'identical'
  42299.    connection is a connection that was opened to the same host, with
  42300.    the same username and the same password (where applicable).
  42301.   </P
  42302. ><P
  42303. >    People who aren't thoroughly familiar with the way web servers work
  42304.    and distribute the load may mistake persistent connects for what
  42305.    they're not. In particular, they do <SPAN
  42306. CLASS="emphasis"
  42307. ><I
  42308. CLASS="emphasis"
  42309. >not</I
  42310. ></SPAN
  42311. > give
  42312.    you an ability to open 'user sessions' on the same link, they
  42313.    do <SPAN
  42314. CLASS="emphasis"
  42315. ><I
  42316. CLASS="emphasis"
  42317. >not</I
  42318. ></SPAN
  42319. > give you an ability to build up a
  42320.    transaction efficiently, and they don't do a whole lot of other
  42321.    things. In fact, to be extremely clear about the subject,
  42322.    persistent connections don't give you <SPAN
  42323. CLASS="emphasis"
  42324. ><I
  42325. CLASS="emphasis"
  42326. >any</I
  42327. ></SPAN
  42328. >
  42329.    functionality that wasn't possible with their non-persistent
  42330.    brothers.
  42331.   </P
  42332. ><P
  42333. >    Why?
  42334.   </P
  42335. ><P
  42336. >    This has to do with the way web servers work. There are three ways
  42337.    in which your web server can utilize PHP to generate web pages.
  42338.   </P
  42339. ><P
  42340. >    The first method is to use PHP as a CGI "wrapper". When run this
  42341.    way, an instance of the PHP interpreter is created and destroyed
  42342.    for every page request (for a PHP page) to your web server.
  42343.    Because it is destroyed after every request, any resources that it
  42344.    acquires (such as a link to an SQL database server) are closed when
  42345.    it is destroyed. In this case, you do not gain anything from trying
  42346.    to use persistent connections -- they simply don't persist.
  42347.   </P
  42348. ><P
  42349. >    The second, and most popular, method is to run PHP as a module in a
  42350.    multiprocess web server, which currently only includes Apache. A
  42351.    multiprocess server typically has one process (the parent) which
  42352.    coordinates a set of processes (its children) who actually do the
  42353.    work of serving up web pages. When a request comes in from a
  42354.    client, it is handed off to one of the children that is not already
  42355.    serving another client. This means that when the same client makes
  42356.    a second request to the server, it may be served by a different
  42357.    child process than the first time. When opening a persistent connection, 
  42358.    every following page requesting SQL services can reuse the same 
  42359.    established connection to the SQL server.
  42360.   </P
  42361. ><P
  42362. >    The last method is to use PHP as a plug-in for a multithreaded web
  42363.    server. Currently PHP 4 has support for ISAPI, WSAPI, and NSAPI (on
  42364.    Windows), which all allow PHP to be used as a plug-in on multithreaded
  42365.    servers like Netscape FastTrack (iPlanet), Microsoft's Internet Information
  42366.    Server (IIS), and O'Reilly's WebSite Pro. The behavior is essentially
  42367.    the same as for the multiprocess model described before. Note that
  42368.    SAPI support is not available in PHP 3.
  42369.   </P
  42370. ><P
  42371. >    If persistent connections don't have any added functionality, what
  42372.    are they good for?
  42373.   </P
  42374. ><P
  42375. >    The answer here is extremely simple -- efficiency. Persistent
  42376.    connections are good if the overhead to create a link to your SQL
  42377.    server is high. Whether or not this overhead is really high depends
  42378.    on many factors. Like, what kind of database it is, whether or not
  42379.    it sits on the same computer on which your web server sits, how
  42380.    loaded the machine the SQL server sits on is and so forth. The
  42381.    bottom line is that if that connection overhead is high, persistent
  42382.    connections help you considerably. They cause the child process to
  42383.    simply connect only once for its entire lifespan, instead of every
  42384.    time it processes a page that requires connecting to the SQL
  42385.    server. This means that for every child that opened a persistent
  42386.    connection will have its own open persistent connection to the
  42387.    server. For example, if you had 20 different child processes that
  42388.    ran a script that made a persistent connection to your SQL server,
  42389.    you'd have 20 different connections to the SQL server, one from
  42390.    each child.
  42391.   </P
  42392. ><P
  42393. >    Note, however, that this can have some drawbacks if you are using a
  42394.    database with connection limits that are exceeded by persistent
  42395.    child connections. If your database has a limit of 16 simultaneous
  42396.    connections, and in the course of a busy server session, 17 child
  42397.    threads attempt to connect, one will not be able to. If there are
  42398.    bugs in your scripts which do not allow the connections to shut
  42399.    down (such as infinite loops), the database with only 16 connections
  42400.    may be rapidly swamped. Check your database documentation for
  42401.    information on handling abandoned or idle connections.
  42402.   </P
  42403. ><DIV
  42404. CLASS="warning"
  42405. ><P
  42406. ></P
  42407. ><TABLE
  42408. CLASS="warning"
  42409. BORDER="1"
  42410. WIDTH="100%"
  42411. ><TR
  42412. ><TD
  42413. ALIGN="CENTER"
  42414. ><B
  42415. >Warning</B
  42416. ></TD
  42417. ></TR
  42418. ><TR
  42419. ><TD
  42420. ALIGN="LEFT"
  42421. ><P
  42422. >     There are a couple of additional caveats to keep in mind when
  42423.     using persistent connections. One is that when using table
  42424.     locking on a persistent connection, if the script for whatever
  42425.     reason cannot release the lock, then subsequent scripts using the
  42426.     same connection will block indefinitely and may require that you
  42427.     either restart the httpd server or the database server. Another is
  42428.     that when using transactions, a transaction block will also carry
  42429.     over to the next script which uses that connection if script execution
  42430.     ends before the transaction block does. In either case, you can
  42431.     use <A
  42432. HREF="#function.register-shutdown-function"
  42433. ><B
  42434. CLASS="function"
  42435. >register_shutdown_function()</B
  42436. ></A
  42437. > to register a
  42438.     simple cleanup function to unlock your tables or roll back your
  42439.     transactions. Better yet, avoid the problem entirely by not using
  42440.     persistent connections in scripts which use table locks or
  42441.     transactions (you can still use them elsewhere).
  42442.    </P
  42443. ></TD
  42444. ></TR
  42445. ></TABLE
  42446. ></DIV
  42447. ><P
  42448. >    An important summary. Persistent connections were designed to have
  42449.    one-to-one mapping to regular connections. That means that you
  42450.    should <SPAN
  42451. CLASS="emphasis"
  42452. ><I
  42453. CLASS="emphasis"
  42454. >always</I
  42455. ></SPAN
  42456. > be able to replace persistent
  42457.    connections with non-persistent connections, and it won't change
  42458.    the way your script behaves. It <SPAN
  42459. CLASS="emphasis"
  42460. ><I
  42461. CLASS="emphasis"
  42462. >may</I
  42463. ></SPAN
  42464. > (and
  42465.    probably will) change the efficiency of the script, but not its
  42466.    behavior!
  42467.   </P
  42468. ><P
  42469. >    See also <A
  42470. HREF="#function.fbsql-pconnect"
  42471. ><B
  42472. CLASS="function"
  42473. >fbsql_pconnect()</B
  42474. ></A
  42475. >,
  42476.    <A
  42477. HREF="#function.ibase-pconnect"
  42478. ><B
  42479. CLASS="function"
  42480. >ibase_pconnect()</B
  42481. ></A
  42482. >, <A
  42483. HREF="#function.ifx-pconnect"
  42484. ><B
  42485. CLASS="function"
  42486. >ifx_pconnect()</B
  42487. ></A
  42488. >,
  42489.    <A
  42490. HREF="#function.ingres-pconnect"
  42491. ><B
  42492. CLASS="function"
  42493. >ingres_pconnect()</B
  42494. ></A
  42495. >,
  42496.    <A
  42497. HREF="#function.msql-pconnect"
  42498. ><B
  42499. CLASS="function"
  42500. >msql_pconnect()</B
  42501. ></A
  42502. >, <A
  42503. HREF="#function.mssql-pconnect"
  42504. ><B
  42505. CLASS="function"
  42506. >mssql_pconnect()</B
  42507. ></A
  42508. >,
  42509.    <A
  42510. HREF="#function.mysql-pconnect"
  42511. ><B
  42512. CLASS="function"
  42513. >mysql_pconnect()</B
  42514. ></A
  42515. >, <A
  42516. HREF="#function.ociplogon"
  42517. ><B
  42518. CLASS="function"
  42519. >ociplogon()</B
  42520. ></A
  42521. >,
  42522.    <A
  42523. HREF="#function.odbc-pconnect"
  42524. ><B
  42525. CLASS="function"
  42526. >odbc_pconnect()</B
  42527. ></A
  42528. >, <A
  42529. HREF="#function.ora-plogon"
  42530. ><B
  42531. CLASS="function"
  42532. >ora_plogon()</B
  42533. ></A
  42534. >,
  42535.    <A
  42536. HREF="#function.pfsockopen"
  42537. ><B
  42538. CLASS="function"
  42539. >pfsockopen()</B
  42540. ></A
  42541. >, <A
  42542. HREF="#function.pg-pconnect"
  42543. ><B
  42544. CLASS="function"
  42545. >pg_pconnect()</B
  42546. ></A
  42547. >, and
  42548.    <A
  42549. HREF="#function.sybase-pconnect"
  42550. ><B
  42551. CLASS="function"
  42552. >sybase_pconnect()</B
  42553. ></A
  42554. >.
  42555.   </P
  42556. ></DIV
  42557. ><DIV
  42558. CLASS="chapter"
  42559. ><HR><H1
  42560. ><A
  42561. NAME="features.safe-mode"
  42562. >Chapter 42. Safe Mode</A
  42563. ></H1
  42564. ><P
  42565. >    The PHP safe mode is an attempt to solve the shared-server security
  42566.    problem. It is architecturally incorrect to try to solve this
  42567.    problem at the PHP level, but since the alternatives at the web
  42568.    server and OS levels aren't very realistic, many people,
  42569.    especially ISP's, use safe mode for now. 
  42570.   </P
  42571. ><DIV
  42572. CLASS="sect1"
  42573. ><HR><H2
  42574. CLASS="sect1"
  42575. ><A
  42576. NAME="ini.sect.safe-mode"
  42577. >Security and Safe Mode</A
  42578. ></H2
  42579. ><P
  42580. >     <DIV
  42581. CLASS="table"
  42582. ><A
  42583. NAME="AEN6936"
  42584. ></A
  42585. ><P
  42586. ><B
  42587. >Table 42-1. Security and Safe Mode Configuration Directives</B
  42588. ></P
  42589. ><TABLE
  42590. BORDER="1"
  42591. CLASS="CALSTABLE"
  42592. ><COL><COL><COL><THEAD
  42593. ><TR
  42594. ><TH
  42595. >Name</TH
  42596. ><TH
  42597. >Default</TH
  42598. ><TH
  42599. >Changeable</TH
  42600. ></TR
  42601. ></THEAD
  42602. ><TBODY
  42603. ><TR
  42604. ><TD
  42605. >safe_mode</TD
  42606. ><TD
  42607. >"0"</TD
  42608. ><TD
  42609. >PHP_INI_SYSTEM</TD
  42610. ></TR
  42611. ><TR
  42612. ><TD
  42613. >safe_mode_gid</TD
  42614. ><TD
  42615. >"0"</TD
  42616. ><TD
  42617. >PHP_INI_SYSTEM</TD
  42618. ></TR
  42619. ><TR
  42620. ><TD
  42621. >safe_mode_include_dir</TD
  42622. ><TD
  42623. >NULL</TD
  42624. ><TD
  42625. >PHP_INI_SYSTEM</TD
  42626. ></TR
  42627. ><TR
  42628. ><TD
  42629. >safe_mode_exec_dir</TD
  42630. ><TD
  42631. >""</TD
  42632. ><TD
  42633. >PHP_INI_SYSTEM</TD
  42634. ></TR
  42635. ><TR
  42636. ><TD
  42637. >safe_mode_allowed_env_vars</TD
  42638. ><TD
  42639. >PHP_</TD
  42640. ><TD
  42641. >PHP_INI_SYSTEM</TD
  42642. ></TR
  42643. ><TR
  42644. ><TD
  42645. >safe_mode_protected_env_vars</TD
  42646. ><TD
  42647. >LD_LIBRARY_PATH</TD
  42648. ><TD
  42649. >PHP_INI_SYSTEM</TD
  42650. ></TR
  42651. ><TR
  42652. ><TD
  42653. >open_basedir</TD
  42654. ><TD
  42655. >NULL</TD
  42656. ><TD
  42657. >PHP_INI_SYSTEM</TD
  42658. ></TR
  42659. ><TR
  42660. ><TD
  42661. >disable_functions</TD
  42662. ><TD
  42663. >""</TD
  42664. ><TD
  42665. >PHP_INI_SYSTEM</TD
  42666. ></TR
  42667. ><TR
  42668. ><TD
  42669. >disable_classes</TD
  42670. ><TD
  42671. >""</TD
  42672. ><TD
  42673. >PHP_INI_SYSTEM</TD
  42674. ></TR
  42675. ></TBODY
  42676. ></TABLE
  42677. ></DIV
  42678. >
  42679.     For further details and definition of the PHP_INI_* constants see
  42680.     <A
  42681. HREF="#function.ini-set"
  42682. ><B
  42683. CLASS="function"
  42684. >ini_set()</B
  42685. ></A
  42686. >.
  42687.    </P
  42688. ><P
  42689. >Here's a short explanation of
  42690. the configuration directives.</P
  42691. ><P
  42692. >     <P
  42693. ></P
  42694. ><DIV
  42695. CLASS="variablelist"
  42696. ><DL
  42697. ><DT
  42698. ><A
  42699. NAME="ini.safe-mode"
  42700. ></A
  42701. ><VAR
  42702. CLASS="parameter"
  42703. >safe_mode</VAR
  42704. >
  42705.        <A
  42706. HREF="#language.types.boolean"
  42707. ><B
  42708. CLASS="type"
  42709. >boolean</B
  42710. ></A
  42711. ></DT
  42712. ><DD
  42713. ><P
  42714. >         Whether to enable PHP's safe mode. Read the
  42715.         <A
  42716. HREF="#security"
  42717. >Security</A
  42718. > chapter for more
  42719.         information.
  42720.        </P
  42721. ></DD
  42722. ><DT
  42723. ><A
  42724. NAME="ini.safe-mode-gid"
  42725. ></A
  42726. ><VAR
  42727. CLASS="parameter"
  42728. >safe_mode_gid</VAR
  42729. >
  42730.        <A
  42731. HREF="#language.types.boolean"
  42732. ><B
  42733. CLASS="type"
  42734. >boolean</B
  42735. ></A
  42736. ></DT
  42737. ><DD
  42738. ><P
  42739. >         By default, Safe Mode does a UID compare check when
  42740.         opening files. If you want to relax this to a GID compare,
  42741.         then turn on safe_mode_gid.
  42742.         Whether to use <VAR
  42743. CLASS="literal"
  42744. >UID</VAR
  42745. > (<TT
  42746. CLASS="constant"
  42747. ><B
  42748. >FALSE</B
  42749. ></TT
  42750. >) or
  42751.         <VAR
  42752. CLASS="literal"
  42753. >GID</VAR
  42754. > (<TT
  42755. CLASS="constant"
  42756. ><B
  42757. >TRUE</B
  42758. ></TT
  42759. >) checking upon file
  42760.         access.
  42761.        </P
  42762. ></DD
  42763. ><DT
  42764. ><A
  42765. NAME="ini.safe-mode-include-dir"
  42766. ></A
  42767. ><VAR
  42768. CLASS="parameter"
  42769. >safe_mode_include_dir</VAR
  42770. >
  42771.        <A
  42772. HREF="#language.types.string"
  42773. ><B
  42774. CLASS="type"
  42775. >string</B
  42776. ></A
  42777. ></DT
  42778. ><DD
  42779. ><P
  42780. >         <VAR
  42781. CLASS="literal"
  42782. >UID</VAR
  42783. >/<VAR
  42784. CLASS="literal"
  42785. >GID</VAR
  42786. > checks are bypassed when
  42787.         including files from this directory and its subdirectories (directory
  42788.         must also be in <A
  42789. HREF="#ini.include-path"
  42790. >include_path</A
  42791. >
  42792.         or full path must including).
  42793.        </P
  42794. ><P
  42795. >         As of PHP 4.2.0, this directive can take a colon (semi-colon on
  42796.         Windows) separated path in a fashion similar to the
  42797.         <A
  42798. HREF="#ini.include-path"
  42799. >include_path</A
  42800. > directive,
  42801.         rather than just a single directory.
  42802.        </P
  42803. ><P
  42804. >         The restriction specified is actually a prefix, not a directory name. 
  42805.         This means that "safe_mode_include_dir = /dir/incl" also allows
  42806.         access to "/dir/include" and "/dir/incls" if they exist.  When you 
  42807.         want to restrict access to only the specified directory, end with a 
  42808.         slash. For example: "safe_mode_include_dir = /dir/incl/"
  42809.        </P
  42810. ></DD
  42811. ><DT
  42812. ><A
  42813. NAME="ini.safe-mode-exec-dir"
  42814. ></A
  42815. ><VAR
  42816. CLASS="parameter"
  42817. >safe_mode_exec_dir</VAR
  42818. >
  42819.        <A
  42820. HREF="#language.types.string"
  42821. ><B
  42822. CLASS="type"
  42823. >string</B
  42824. ></A
  42825. ></DT
  42826. ><DD
  42827. ><P
  42828. >         If PHP is used in safe mode, <A
  42829. HREF="#function.system"
  42830. ><B
  42831. CLASS="function"
  42832. >system()</B
  42833. ></A
  42834. > and the other
  42835.         <A
  42836. HREF="#ref.exec"
  42837. >functions executing system programs</A
  42838. >
  42839.         refuse to start programs that are not in this directory.
  42840.         You have to use <VAR
  42841. CLASS="literal"
  42842. >/</VAR
  42843. > as directory separator on all
  42844.         environments including Windows.
  42845.        </P
  42846. ></DD
  42847. ><DT
  42848. ><A
  42849. NAME="ini.safe-mode-allowed-env-vars"
  42850. ></A
  42851. ><VAR
  42852. CLASS="parameter"
  42853. >safe_mode_allowed_env_vars</VAR
  42854. >
  42855.        <A
  42856. HREF="#language.types.string"
  42857. ><B
  42858. CLASS="type"
  42859. >string</B
  42860. ></A
  42861. ></DT
  42862. ><DD
  42863. ><P
  42864. >         Setting certain environment variables may be a potential security breach.
  42865.         This directive contains a comma-delimited list of prefixes. In Safe Mode,
  42866.         the user may only alter environment variables whose names begin with the
  42867.         prefixes supplied here. By default, users will only be able to set
  42868.         environment variables that begin with PHP_ (e.g. PHP_FOO=BAR).
  42869.        </P
  42870. ><DIV
  42871. CLASS="note"
  42872. ><BLOCKQUOTE
  42873. CLASS="note"
  42874. ><P
  42875. ><B
  42876. >Note: </B
  42877. >
  42878.          If this directive is empty, PHP will let the user modify ANY
  42879.          environment variable!
  42880.         </P
  42881. ></BLOCKQUOTE
  42882. ></DIV
  42883. ></DD
  42884. ><DT
  42885. ><A
  42886. NAME="ini.safe-mode-protected-env-vars"
  42887. ></A
  42888. ><VAR
  42889. CLASS="parameter"
  42890. >safe_mode_protected_env_vars</VAR
  42891. >
  42892.        <A
  42893. HREF="#language.types.string"
  42894. ><B
  42895. CLASS="type"
  42896. >string</B
  42897. ></A
  42898. ></DT
  42899. ><DD
  42900. ><P
  42901. >         This directive contains a comma-delimited list of environment
  42902.         variables that the end user won't be able to change using
  42903.         <A
  42904. HREF="#function.putenv"
  42905. ><B
  42906. CLASS="function"
  42907. >putenv()</B
  42908. ></A
  42909. >. These variables will be protected
  42910.         even if safe_mode_allowed_env_vars is set to allow to change them.
  42911.        </P
  42912. ></DD
  42913. ><DT
  42914. ><A
  42915. NAME="ini.open-basedir"
  42916. ></A
  42917. ><VAR
  42918. CLASS="parameter"
  42919. >open_basedir</VAR
  42920. >
  42921.        <A
  42922. HREF="#language.types.string"
  42923. ><B
  42924. CLASS="type"
  42925. >string</B
  42926. ></A
  42927. ></DT
  42928. ><DD
  42929. ><P
  42930. >         Limit the files that can be opened by PHP to the specified
  42931.         directory-tree, including the file itself.  This directive 
  42932.         is <SPAN
  42933. CLASS="emphasis"
  42934. ><I
  42935. CLASS="emphasis"
  42936. >NOT</I
  42937. ></SPAN
  42938. > affected by whether Safe Mode is 
  42939.         turned On or Off.
  42940.        </P
  42941. ><P
  42942. >         When a script tries to open a file with, for example,
  42943.         <A
  42944. HREF="#function.fopen"
  42945. ><B
  42946. CLASS="function"
  42947. >fopen()</B
  42948. ></A
  42949. > or <A
  42950. HREF="#function.gzopen"
  42951. ><B
  42952. CLASS="function"
  42953. >gzopen()</B
  42954. ></A
  42955. >,
  42956.         the location of the file is checked. When the file is outside the
  42957.         specified directory-tree, PHP will refuse to open it. All symbolic
  42958.         links are resolved, so it's not possible to avoid this restriction
  42959.         with a symlink.
  42960.        </P
  42961. ><P
  42962. >         The special value <SPAN
  42963. CLASS="systemitem"
  42964. >.</SPAN
  42965. >
  42966.         indicates that the working directory of the script will be used as the
  42967.         base-directory. This is, however, a little dangerous as the working directory
  42968.         of the script can easily be changed with <A
  42969. HREF="#function.chdir"
  42970. ><B
  42971. CLASS="function"
  42972. >chdir()</B
  42973. ></A
  42974. >.
  42975.        </P
  42976. ><P
  42977. >         In <TT
  42978. CLASS="filename"
  42979. >httpd.conf</TT
  42980. >, open_basedir can be turned off
  42981.         (e.g. for some virtual hosts)
  42982.         <A
  42983. HREF="#configuration.changes.apache"
  42984. >the same way</A
  42985. > as
  42986.         any other configuration directive with "php_admin_value open_basedir
  42987.         none".
  42988.        </P
  42989. ><P
  42990. >         Under Windows, separate the directories with a semicolon. On all
  42991.         other systems, separate the directories with a colon. As an Apache
  42992.         module, open_basedir paths from parent directories are now
  42993.         automatically inherited.
  42994.        </P
  42995. ><P
  42996. >          The restriction specified with open_basedir is actually a
  42997.          prefix, not a directory name.  This means that "open_basedir =
  42998.          /dir/incl" also allows access to "/dir/include" and
  42999.          "/dir/incls" if they exist. When you want to restrict access
  43000.          to only the specified directory, end with a slash. For example:
  43001.          "open_basedir = /dir/incl/"
  43002.        </P
  43003. ><DIV
  43004. CLASS="note"
  43005. ><BLOCKQUOTE
  43006. CLASS="note"
  43007. ><P
  43008. ><B
  43009. >Note: </B
  43010. >
  43011.          Support for multiple directories was added in 3.0.7.
  43012.         </P
  43013. ></BLOCKQUOTE
  43014. ></DIV
  43015. ><P
  43016. >         The default is to allow all files to be opened.
  43017.        </P
  43018. ></DD
  43019. ><DT
  43020. ><A
  43021. NAME="ini.disable-functions"
  43022. ></A
  43023. ><VAR
  43024. CLASS="parameter"
  43025. >disable_functions</VAR
  43026. >
  43027.        <A
  43028. HREF="#language.types.string"
  43029. ><B
  43030. CLASS="type"
  43031. >string</B
  43032. ></A
  43033. ></DT
  43034. ><DD
  43035. ><P
  43036. >         This directive allows you to disable certain functions for 
  43037.         <A
  43038. HREF="#security"
  43039. >security</A
  43040. > reasons. It takes 
  43041.         on a comma-delimited list of function names. disable_functions
  43042.         is not affected by <A
  43043. HREF="#ini.safe-mode"
  43044. >Safe Mode</A
  43045. >.
  43046.        </P
  43047. ><P
  43048. >         This directive must be set in <TT
  43049. CLASS="filename"
  43050. >php.ini</TT
  43051. > For example, you 
  43052.         cannot set this in <TT
  43053. CLASS="filename"
  43054. >httpd.conf</TT
  43055. >.
  43056.        </P
  43057. ></DD
  43058. ><DT
  43059. ><A
  43060. NAME="ini.disable-classes"
  43061. ></A
  43062. ><VAR
  43063. CLASS="parameter"
  43064. >disable_classes</VAR
  43065. >
  43066.        <A
  43067. HREF="#language.types.string"
  43068. ><B
  43069. CLASS="type"
  43070. >string</B
  43071. ></A
  43072. ></DT
  43073. ><DD
  43074. ><P
  43075. >         This directive allows you to disable certain classes for
  43076.         <A
  43077. HREF="#security"
  43078. >security</A
  43079. > reasons.  It takes
  43080.         on a comma-delimited list of class names.  disable_classes
  43081.         is not affected by <A
  43082. HREF="#ini.safe-mode"
  43083. >Safe Mode</A
  43084. >.
  43085.        </P
  43086. ><P
  43087. >         This directive must be set in <TT
  43088. CLASS="filename"
  43089. >php.ini</TT
  43090. >  For example, you
  43091.         cannot set this in <TT
  43092. CLASS="filename"
  43093. >httpd.conf</TT
  43094. >.
  43095.        </P
  43096. ><DIV
  43097. CLASS="note"
  43098. ><BLOCKQUOTE
  43099. CLASS="note"
  43100. ><P
  43101. ><B
  43102. >Availability note: </B
  43103. >
  43104.          This directive became available in PHP 4.3.2
  43105.         </P
  43106. ></BLOCKQUOTE
  43107. ></DIV
  43108. ></DD
  43109. ></DL
  43110. ></DIV
  43111. >
  43112.    </P
  43113. ><P
  43114. >     See also: <A
  43115. HREF="#ini.register-globals"
  43116. >register_globals</A
  43117. >,
  43118.     <A
  43119. HREF="#ini.display-errors"
  43120. >display_errors</A
  43121. >, and
  43122.     <A
  43123. HREF="#ini.log-errors"
  43124. >log_errors</A
  43125. >
  43126.    </P
  43127. ><P
  43128. >    When <A
  43129. HREF="#ini.safe-mode"
  43130. >safe_mode</A
  43131. > is on, PHP checks to see 
  43132.    if the owner of the current script matches the owner of the file to be 
  43133.    operated on by a file function or its directory. For example: 
  43134.    <TABLE
  43135. BORDER="0"
  43136. BGCOLOR="#E0E0E0"
  43137. CELLPADDING="5"
  43138. ><TR
  43139. ><TD
  43140. ><PRE
  43141. CLASS="ls"
  43142. >-rw-rw-r--    1 rasmus   rasmus       33 Jul  1 19:20 script.php 
  43143. -rw-r--r--    1 root     root       1116 May 26 18:01 /etc/passwd</PRE
  43144. ></TD
  43145. ></TR
  43146. ></TABLE
  43147. >
  43148.    Running this script.php 
  43149.    <TABLE
  43150. BORDER="0"
  43151. BGCOLOR="#E0E0E0"
  43152. CELLPADDING="5"
  43153. ><TR
  43154. ><TD
  43155. ><PRE
  43156. CLASS="php"
  43157. ><?php
  43158.  readfile('/etc/passwd'); 
  43159. ?></PRE
  43160. ></TD
  43161. ></TR
  43162. ></TABLE
  43163. >
  43164.    results in this error when safe mode is enabled: 
  43165.    <TABLE
  43166. BORDER="0"
  43167. BGCOLOR="#E0E0E0"
  43168. CELLPADDING="5"
  43169. ><TR
  43170. ><TD
  43171. ><PRE
  43172. CLASS="screen"
  43173. >Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not 
  43174. allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2</PRE
  43175. ></TD
  43176. ></TR
  43177. ></TABLE
  43178. >
  43179.   </P
  43180. ><P
  43181. >    However, there may be environments where a strict <VAR
  43182. CLASS="literal"
  43183. >UID</VAR
  43184. >
  43185.    check is not appropriate and a relaxed <VAR
  43186. CLASS="literal"
  43187. >GID</VAR
  43188. > check is
  43189.    sufficient.  This is supported by means of the <A
  43190. HREF="#ini.safe-mode-gid"
  43191. >safe_mode_gid</A
  43192. > switch. Setting it to
  43193.    <VAR
  43194. CLASS="literal"
  43195. >On</VAR
  43196. > performs the relaxed <VAR
  43197. CLASS="literal"
  43198. >GID</VAR
  43199. > checking,
  43200.    setting it to <VAR
  43201. CLASS="literal"
  43202. >Off</VAR
  43203. > (the default) performs
  43204.    <VAR
  43205. CLASS="literal"
  43206. >UID</VAR
  43207. > checking.
  43208.   </P
  43209. ><P
  43210. >    If instead of <A
  43211. HREF="#ini.safe-mode"
  43212. >safe_mode</A
  43213. >, you set an 
  43214.    <A
  43215. HREF="#ini.open-basedir"
  43216. >open_basedir</A
  43217. > directory then all
  43218.    file operations will be limited to files under the specified directory
  43219.    For example (Apache <TT
  43220. CLASS="filename"
  43221. >httpd.conf</TT
  43222. > example): 
  43223.    <TABLE
  43224. BORDER="0"
  43225. BGCOLOR="#E0E0E0"
  43226. CELLPADDING="5"
  43227. ><TR
  43228. ><TD
  43229. ><PRE
  43230. CLASS="ini"
  43231. ><Directory /docroot>
  43232.   php_admin_value open_basedir /docroot 
  43233. </Directory></PRE
  43234. ></TD
  43235. ></TR
  43236. ></TABLE
  43237. >
  43238.    If you run the same script.php with this
  43239.    <A
  43240. HREF="#ini.open-basedir"
  43241. >open_basedir</A
  43242. > setting
  43243.    then this is the result: 
  43244.    <TABLE
  43245. BORDER="0"
  43246. BGCOLOR="#E0E0E0"
  43247. CELLPADDING="5"
  43248. ><TR
  43249. ><TD
  43250. ><PRE
  43251. CLASS="screen"
  43252. >Warning: open_basedir restriction in effect. File is in wrong directory in 
  43253. /docroot/script.php on line 2</PRE
  43254. ></TD
  43255. ></TR
  43256. ></TABLE
  43257. >
  43258.   </P
  43259. ><P
  43260. >    You can also disable individual functions. Note that the
  43261.    <A
  43262. HREF="#ini.disable-functions"
  43263. >disable_functions</A
  43264. >
  43265.    directive can not be used outside of the <TT
  43266. CLASS="filename"
  43267. >php.ini</TT
  43268. > file which means that
  43269.    you cannot disable functions on a per-virtualhost or per-directory basis
  43270.    in your <TT
  43271. CLASS="filename"
  43272. >httpd.conf</TT
  43273. > file.
  43274.    If we add this to our <TT
  43275. CLASS="filename"
  43276. >php.ini</TT
  43277. > file: 
  43278.    <TABLE
  43279. BORDER="0"
  43280. BGCOLOR="#E0E0E0"
  43281. CELLPADDING="5"
  43282. ><TR
  43283. ><TD
  43284. ><PRE
  43285. CLASS="ini"
  43286. >disable_functions readfile,system</PRE
  43287. ></TD
  43288. ></TR
  43289. ></TABLE
  43290. >
  43291.    Then we get this output: 
  43292.    <TABLE
  43293. BORDER="0"
  43294. BGCOLOR="#E0E0E0"
  43295. CELLPADDING="5"
  43296. ><TR
  43297. ><TD
  43298. ><PRE
  43299. CLASS="screen"
  43300. >Warning: readfile() has been disabled for security reasons in 
  43301. /docroot/script.php on line 2</PRE
  43302. ></TD
  43303. ></TR
  43304. ></TABLE
  43305. >
  43306.   </P
  43307. ></DIV
  43308. ><DIV
  43309. CLASS="sect1"
  43310. ><HR><H2
  43311. CLASS="sect1"
  43312. ><A
  43313. NAME="features.safe-mode.functions"
  43314. >Functions restricted/disabled by safe mode</A
  43315. ></H2
  43316. ><P
  43317. >     This is a still probably incomplete and possibly incorrect listing
  43318.     of the functions limited by 
  43319.     <A
  43320. HREF="#features.safe-mode"
  43321. >safe mode</A
  43322. >.
  43323.     
  43324.     <DIV
  43325. CLASS="table"
  43326. ><A
  43327. NAME="AEN7119"
  43328. ></A
  43329. ><P
  43330. ><B
  43331. >Table 42-2. Safe mode limited functions</B
  43332. ></P
  43333. ><TABLE
  43334. BORDER="1"
  43335. CLASS="CALSTABLE"
  43336. ><COL><COL><THEAD
  43337. ><TR
  43338. ><TH
  43339. >Function</TH
  43340. ><TH
  43341. >Limitations</TH
  43342. ></TR
  43343. ></THEAD
  43344. ><TBODY
  43345. ><TR
  43346. ><TD
  43347. ><A
  43348. HREF="#function.dbmopen"
  43349. ><B
  43350. CLASS="function"
  43351. >dbmopen()</B
  43352. ></A
  43353. ></TD
  43354. ><TD
  43355. >Checks whether the files or directories you are 
  43356. about to operate on have the same UID (owner) as the script that is being
  43357. executed.</TD
  43358. ></TR
  43359. ><TR
  43360. ><TD
  43361. ><A
  43362. HREF="#function.dbase-open"
  43363. ><B
  43364. CLASS="function"
  43365. >dbase_open()</B
  43366. ></A
  43367. ></TD
  43368. ><TD
  43369. >Checks whether the files or directories you are 
  43370. about to operate on have the same UID (owner) as the script that is being
  43371. executed.</TD
  43372. ></TR
  43373. ><TR
  43374. ><TD
  43375. ><A
  43376. HREF="#function.filepro"
  43377. ><B
  43378. CLASS="function"
  43379. >filepro()</B
  43380. ></A
  43381. ></TD
  43382. ><TD
  43383. >Checks whether the files or directories you are 
  43384. about to operate on have the same UID (owner) as the script that is being
  43385. executed.</TD
  43386. ></TR
  43387. ><TR
  43388. ><TD
  43389. ><A
  43390. HREF="#function.filepro-rowcount"
  43391. ><B
  43392. CLASS="function"
  43393. >filepro_rowcount()</B
  43394. ></A
  43395. ></TD
  43396. ><TD
  43397. >Checks whether the files or directories you are 
  43398. about to operate on have the same UID (owner) as the script that is being
  43399. executed.</TD
  43400. ></TR
  43401. ><TR
  43402. ><TD
  43403. ><A
  43404. HREF="#function.filepro-retrieve"
  43405. ><B
  43406. CLASS="function"
  43407. >filepro_retrieve()</B
  43408. ></A
  43409. ></TD
  43410. ><TD
  43411. >Checks whether the files or directories you are 
  43412. about to operate on have the same UID (owner) as the script that is being
  43413. executed.</TD
  43414. ></TR
  43415. ><TR
  43416. ><TD
  43417. >ifx_*</TD
  43418. ><TD
  43419. >sql_safe_mode restrictions, (!= safe mode)</TD
  43420. ></TR
  43421. ><TR
  43422. ><TD
  43423. >ingres_*</TD
  43424. ><TD
  43425. >sql_safe_mode restrictions, (!= safe mode)</TD
  43426. ></TR
  43427. ><TR
  43428. ><TD
  43429. >mysql_*</TD
  43430. ><TD
  43431. >sql_safe_mode restrictions, (!= safe mode)</TD
  43432. ></TR
  43433. ><TR
  43434. ><TD
  43435. ><A
  43436. HREF="#function.pg-lo-import"
  43437. ><B
  43438. CLASS="function"
  43439. >pg_lo_import()</B
  43440. ></A
  43441. ></TD
  43442. ><TD
  43443. >Checks whether the files or directories you are 
  43444. about to operate on have the same UID (owner) as the script that is being
  43445. executed.</TD
  43446. ></TR
  43447. ><TR
  43448. ><TD
  43449. ><A
  43450. HREF="#function.posix-mkfifo"
  43451. ><B
  43452. CLASS="function"
  43453. >posix_mkfifo()</B
  43454. ></A
  43455. ></TD
  43456. ><TD
  43457. >Checks whether the directory in which
  43458. you are about to operate has the same UID (owner) as the script that is being
  43459. executed.</TD
  43460. ></TR
  43461. ><TR
  43462. ><TD
  43463. ><A
  43464. HREF="#function.putenv"
  43465. ><B
  43466. CLASS="function"
  43467. >putenv()</B
  43468. ></A
  43469. ></TD
  43470. ><TD
  43471. >Obeys the safe_mode_protected_env_vars and 
  43472.         safe_mode_allowed_env_vars ini-directives. See also the documentation
  43473.         on <A
  43474. HREF="#function.putenv"
  43475. ><B
  43476. CLASS="function"
  43477. >putenv()</B
  43478. ></A
  43479. ></TD
  43480. ></TR
  43481. ><TR
  43482. ><TD
  43483. ><A
  43484. HREF="#function.move-uploaded-file"
  43485. ><B
  43486. CLASS="function"
  43487. >move_uploaded_file()</B
  43488. ></A
  43489. ></TD
  43490. ><TD
  43491. >Checks whether the files or directories you are 
  43492. about to operate on have the same UID (owner) as the script that is being
  43493. executed. </TD
  43494. ></TR
  43495. ><TR
  43496. ><TD
  43497. ><A
  43498. HREF="#function.chdir"
  43499. ><B
  43500. CLASS="function"
  43501. >chdir()</B
  43502. ></A
  43503. ></TD
  43504. ><TD
  43505. >Checks whether the directory in which
  43506. you are about to operate has the same UID (owner) as the script that is being
  43507. executed.</TD
  43508. ></TR
  43509. ><TR
  43510. ><TD
  43511. ><A
  43512. HREF="#function.dl"
  43513. ><B
  43514. CLASS="function"
  43515. >dl()</B
  43516. ></A
  43517. ></TD
  43518. ><TD
  43519. >This function is disabled in <A
  43520. HREF="#features.safe-mode"
  43521. >safe mode</A
  43522. >.</TD
  43523. ></TR
  43524. ><TR
  43525. ><TD
  43526. ><A
  43527. HREF="#language.operators.execution"
  43528. >backtick operator</A
  43529. ></TD
  43530. ><TD
  43531. >This function is disabled in <A
  43532. HREF="#features.safe-mode"
  43533. >safe mode</A
  43534. >.</TD
  43535. ></TR
  43536. ><TR
  43537. ><TD
  43538. ><A
  43539. HREF="#function.shell-exec"
  43540. ><B
  43541. CLASS="function"
  43542. >shell_exec()</B
  43543. ></A
  43544. > (functional equivalent 
  43545.         of backticks)</TD
  43546. ><TD
  43547. >This function is disabled in <A
  43548. HREF="#features.safe-mode"
  43549. >safe mode</A
  43550. >.</TD
  43551. ></TR
  43552. ><TR
  43553. ><TD
  43554. ><A
  43555. HREF="#function.exec"
  43556. ><B
  43557. CLASS="function"
  43558. >exec()</B
  43559. ></A
  43560. ></TD
  43561. ><TD
  43562. >You can only execute executables within the <A
  43563. HREF="#ini.safe-mode-exec-dir"
  43564. >safe_mode_exec_dir</A
  43565. >.
  43566.         For practical reasons it's currently not allowed to have
  43567.         <VAR
  43568. CLASS="literal"
  43569. >..</VAR
  43570. > components in the path to the executable.
  43571.         <A
  43572. HREF="#function.escapeshellcmd"
  43573. ><B
  43574. CLASS="function"
  43575. >escapeshellcmd()</B
  43576. ></A
  43577. > is executed on the argument of this
  43578.         function.</TD
  43579. ></TR
  43580. ><TR
  43581. ><TD
  43582. ><A
  43583. HREF="#function.system"
  43584. ><B
  43585. CLASS="function"
  43586. >system()</B
  43587. ></A
  43588. ></TD
  43589. ><TD
  43590. >You can only execute executables within the <A
  43591. HREF="#ini.safe-mode-exec-dir"
  43592. >safe_mode_exec_dir</A
  43593. >.
  43594.         For practical reasons it's currently not allowed to have
  43595.         <VAR
  43596. CLASS="literal"
  43597. >..</VAR
  43598. > components in the path to the executable.
  43599.         <A
  43600. HREF="#function.escapeshellcmd"
  43601. ><B
  43602. CLASS="function"
  43603. >escapeshellcmd()</B
  43604. ></A
  43605. > is executed on the argument of this
  43606.         function.</TD
  43607. ></TR
  43608. ><TR
  43609. ><TD
  43610. ><A
  43611. HREF="#function.passthru"
  43612. ><B
  43613. CLASS="function"
  43614. >passthru()</B
  43615. ></A
  43616. ></TD
  43617. ><TD
  43618. >You can only execute executables within the <A
  43619. HREF="#ini.safe-mode-exec-dir"
  43620. >safe_mode_exec_dir</A
  43621. >.
  43622.         For practical reasons it's currently not allowed to have
  43623.         <VAR
  43624. CLASS="literal"
  43625. >..</VAR
  43626. > components in the path to the executable.
  43627.         <A
  43628. HREF="#function.escapeshellcmd"
  43629. ><B
  43630. CLASS="function"
  43631. >escapeshellcmd()</B
  43632. ></A
  43633. > is executed on the argument of this
  43634.         function.</TD
  43635. ></TR
  43636. ><TR
  43637. ><TD
  43638. ><A
  43639. HREF="#function.popen"
  43640. ><B
  43641. CLASS="function"
  43642. >popen()</B
  43643. ></A
  43644. ></TD
  43645. ><TD
  43646. >You can only execute executables within the <A
  43647. HREF="#ini.safe-mode-exec-dir"
  43648. >safe_mode_exec_dir</A
  43649. >.
  43650.         For practical reasons it's currently not allowed to have
  43651.         <VAR
  43652. CLASS="literal"
  43653. >..</VAR
  43654. > components in the path to the executable.
  43655.         <A
  43656. HREF="#function.escapeshellcmd"
  43657. ><B
  43658. CLASS="function"
  43659. >escapeshellcmd()</B
  43660. ></A
  43661. > is executed on the argument of this
  43662.         function.</TD
  43663. ></TR
  43664. ><TR
  43665. ><TD
  43666. ><A
  43667. HREF="#function.fopen"
  43668. ><B
  43669. CLASS="function"
  43670. >fopen()</B
  43671. ></A
  43672. ></TD
  43673. ><TD
  43674. >Checks whether the directory in which
  43675. you are about to operate has the same UID (owner) as the script that is being
  43676. executed.</TD
  43677. ></TR
  43678. ><TR
  43679. ><TD
  43680. ><A
  43681. HREF="#function.mkdir"
  43682. ><B
  43683. CLASS="function"
  43684. >mkdir()</B
  43685. ></A
  43686. ></TD
  43687. ><TD
  43688. >Checks whether the directory in which
  43689. you are about to operate has the same UID (owner) as the script that is being
  43690. executed.</TD
  43691. ></TR
  43692. ><TR
  43693. ><TD
  43694. ><A
  43695. HREF="#function.rmdir"
  43696. ><B
  43697. CLASS="function"
  43698. >rmdir()</B
  43699. ></A
  43700. ></TD
  43701. ><TD
  43702. >Checks whether the directory in which
  43703. you are about to operate has the same UID (owner) as the script that is being
  43704. executed.</TD
  43705. ></TR
  43706. ><TR
  43707. ><TD
  43708. ><A
  43709. HREF="#function.rename"
  43710. ><B
  43711. CLASS="function"
  43712. >rename()</B
  43713. ></A
  43714. ></TD
  43715. ><TD
  43716. >Checks whether the files or directories you are 
  43717. about to operate on have the same UID (owner) as the script that is being
  43718. executed. Checks whether the directory in which
  43719. you are about to operate has the same UID (owner) as the script that is being
  43720. executed.</TD
  43721. ></TR
  43722. ><TR
  43723. ><TD
  43724. ><A
  43725. HREF="#function.unlink"
  43726. ><B
  43727. CLASS="function"
  43728. >unlink()</B
  43729. ></A
  43730. ></TD
  43731. ><TD
  43732. >Checks whether the files or directories you are 
  43733. about to operate on have the same UID (owner) as the script that is being
  43734. executed. Checks whether the directory in which
  43735. you are about to operate has the same UID (owner) as the script that is being
  43736. executed.</TD
  43737. ></TR
  43738. ><TR
  43739. ><TD
  43740. ><A
  43741. HREF="#function.copy"
  43742. ><B
  43743. CLASS="function"
  43744. >copy()</B
  43745. ></A
  43746. ></TD
  43747. ><TD
  43748. >Checks whether the files or directories you are 
  43749. about to operate on have the same UID (owner) as the script that is being
  43750. executed. Checks whether the directory in which
  43751. you are about to operate has the same UID (owner) as the script that is being
  43752. executed. (on 
  43753.         <VAR
  43754. CLASS="parameter"
  43755. >source</VAR
  43756. > and 
  43757.         <VAR
  43758. CLASS="parameter"
  43759. >target</VAR
  43760. >) </TD
  43761. ></TR
  43762. ><TR
  43763. ><TD
  43764. ><A
  43765. HREF="#function.chgrp"
  43766. ><B
  43767. CLASS="function"
  43768. >chgrp()</B
  43769. ></A
  43770. ></TD
  43771. ><TD
  43772. >Checks whether the files or directories you are 
  43773. about to operate on have the same UID (owner) as the script that is being
  43774. executed.</TD
  43775. ></TR
  43776. ><TR
  43777. ><TD
  43778. ><A
  43779. HREF="#function.chown"
  43780. ><B
  43781. CLASS="function"
  43782. >chown()</B
  43783. ></A
  43784. ></TD
  43785. ><TD
  43786. >Checks whether the files or directories you are 
  43787. about to operate on have the same UID (owner) as the script that is being
  43788. executed.</TD
  43789. ></TR
  43790. ><TR
  43791. ><TD
  43792. ><A
  43793. HREF="#function.chmod"
  43794. ><B
  43795. CLASS="function"
  43796. >chmod()</B
  43797. ></A
  43798. ></TD
  43799. ><TD
  43800. >Checks whether the files or directories you are 
  43801. about to operate on have the same UID (owner) as the script that is being
  43802. executed. In addition, you cannot  
  43803.         set the SUID, SGID and sticky bits</TD
  43804. ></TR
  43805. ><TR
  43806. ><TD
  43807. ><A
  43808. HREF="#function.touch"
  43809. ><B
  43810. CLASS="function"
  43811. >touch()</B
  43812. ></A
  43813. ></TD
  43814. ><TD
  43815. >Checks whether the files or directories you are 
  43816. about to operate on have the same UID (owner) as the script that is being
  43817. executed. Checks whether the directory in which
  43818. you are about to operate has the same UID (owner) as the script that is being
  43819. executed.</TD
  43820. ></TR
  43821. ><TR
  43822. ><TD
  43823. ><A
  43824. HREF="#function.symlink"
  43825. ><B
  43826. CLASS="function"
  43827. >symlink()</B
  43828. ></A
  43829. ></TD
  43830. ><TD
  43831. >Checks whether the files or directories you are 
  43832. about to operate on have the same UID (owner) as the script that is being
  43833. executed. Checks whether the directory in which
  43834. you are about to operate has the same UID (owner) as the script that is being
  43835. executed. (note: only the target is 
  43836.         checked)</TD
  43837. ></TR
  43838. ><TR
  43839. ><TD
  43840. ><A
  43841. HREF="#function.link"
  43842. ><B
  43843. CLASS="function"
  43844. >link()</B
  43845. ></A
  43846. ></TD
  43847. ><TD
  43848. >Checks whether the files or directories you are 
  43849. about to operate on have the same UID (owner) as the script that is being
  43850. executed. Checks whether the directory in which
  43851. you are about to operate has the same UID (owner) as the script that is being
  43852. executed. (note: only the target is 
  43853.         checked)</TD
  43854. ></TR
  43855. ><TR
  43856. ><TD
  43857. ><A
  43858. HREF="#function.apache-request-headers"
  43859. ><B
  43860. CLASS="function"
  43861. >apache_request_headers()</B
  43862. ></A
  43863. ></TD
  43864. ><TD
  43865. >In safe mode, headers beginning with 'authorization' 
  43866.         (case-insensitive) will not be returned.</TD
  43867. ></TR
  43868. ><TR
  43869. ><TD
  43870. ><A
  43871. HREF="#function.header"
  43872. ><B
  43873. CLASS="function"
  43874. >header()</B
  43875. ></A
  43876. ></TD
  43877. ><TD
  43878. >In safe mode, the uid of the script is added to the
  43879.         <VAR
  43880. CLASS="literal"
  43881. >realm</VAR
  43882. > part of the
  43883.         <VAR
  43884. CLASS="literal"
  43885. >WWW-Authenticate</VAR
  43886. > header if you set this
  43887.         header (used for HTTP Authentication).</TD
  43888. ></TR
  43889. ><TR
  43890. ><TD
  43891. ><A
  43892. HREF="#features.http-auth"
  43893. >PHP_AUTH variables</A
  43894. ></TD
  43895. ><TD
  43896. >          In safe mode, the variables <VAR
  43897. CLASS="varname"
  43898. >PHP_AUTH_USER</VAR
  43899. >,
  43900.          <VAR
  43901. CLASS="varname"
  43902. >PHP_AUTH_PW</VAR
  43903. >, and <VAR
  43904. CLASS="varname"
  43905. >AUTH_TYPE</VAR
  43906. >
  43907.          are not available in <VAR
  43908. CLASS="varname"
  43909. >$_SERVER</VAR
  43910. >. Regardless, you
  43911.          can still use <VAR
  43912. CLASS="varname"
  43913. >REMOTE_USER</VAR
  43914. > for the USER.
  43915.          (note: only affected since PHP 4.3.0)
  43916.         </TD
  43917. ></TR
  43918. ><TR
  43919. ><TD
  43920. >          <A
  43921. HREF="#function.highlight-file"
  43922. ><B
  43923. CLASS="function"
  43924. >highlight_file()</B
  43925. ></A
  43926. >,
  43927.          <A
  43928. HREF="#function.show-source"
  43929. ><B
  43930. CLASS="function"
  43931. >show_source()</B
  43932. ></A
  43933. >
  43934.         </TD
  43935. ><TD
  43936. >          Checks whether the files or directories you are 
  43937. about to operate on have the same UID (owner) as the script that is being
  43938. executed. Checks whether the directory in which
  43939. you are about to operate has the same UID (owner) as the script that is being
  43940. executed. (note: only affected since PHP 4.2.1)
  43941.         </TD
  43942. ></TR
  43943. ><TR
  43944. ><TD
  43945. >          <A
  43946. HREF="#function.parse-ini-file"
  43947. ><B
  43948. CLASS="function"
  43949. >parse_ini_file()</B
  43950. ></A
  43951. >
  43952.         </TD
  43953. ><TD
  43954. >          Checks whether the files or directories you are 
  43955. about to operate on have the same UID (owner) as the script that is being
  43956. executed. Checks whether the directory in which
  43957. you are about to operate has the same UID (owner) as the script that is being
  43958. executed. (note: only affected since PHP 4.2.1)
  43959.         </TD
  43960. ></TR
  43961. ><TR
  43962. ><TD
  43963. >          <A
  43964. HREF="#function.set-time-limit"
  43965. ><B
  43966. CLASS="function"
  43967. >set_time_limit()</B
  43968. ></A
  43969. >
  43970.         </TD
  43971. ><TD
  43972. >          Has no affect when PHP is running in <A
  43973. HREF="#ini.safe-mode"
  43974. >safe mode</A
  43975. >.
  43976.         </TD
  43977. ></TR
  43978. ><TR
  43979. ><TD
  43980. >          <A
  43981. HREF="#ini.max-execution-time"
  43982. >max_execution_time</A
  43983. >
  43984.         </TD
  43985. ><TD
  43986. >          Has no affect when PHP is running in <A
  43987. HREF="#ini.safe-mode"
  43988. >safe mode</A
  43989. >.
  43990.         </TD
  43991. ></TR
  43992. ><TR
  43993. ><TD
  43994. >          <A
  43995. HREF="#function.mail"
  43996. ><B
  43997. CLASS="function"
  43998. >mail()</B
  43999. ></A
  44000. >
  44001.         </TD
  44002. ><TD
  44003. >          In safe mode, the fifth parameter is disabled. (note: only affected since PHP 4.2.3)
  44004.         </TD
  44005. ></TR
  44006. ><TR
  44007. ><TD
  44008. >Any function that uses
  44009.          <TT
  44010. CLASS="filename"
  44011. >php4/main/fopen_wrappers.c</TT
  44012. >
  44013.         </TD
  44014. ><TD
  44015. >??</TD
  44016. ></TR
  44017. ></TBODY
  44018. ></TABLE
  44019. ></DIV
  44020. >
  44021.    </P
  44022. ></DIV
  44023. ></DIV
  44024. ><DIV
  44025. CLASS="chapter"
  44026. ><HR><H1
  44027. ><A
  44028. NAME="features.commandline"
  44029. >Chapter 43. Using PHP from the command line</A
  44030. ></H1
  44031. ><P
  44032. >   As of version 4.3.0, PHP supports a new
  44033.   <VAR
  44034. CLASS="literal"
  44035. >SAPI</VAR
  44036. > type (Server Application Programming Interface)
  44037.   named <VAR
  44038. CLASS="literal"
  44039. >CLI</VAR
  44040. > which means <SPAN
  44041. CLASS="emphasis"
  44042. ><I
  44043. CLASS="emphasis"
  44044. >Command Line
  44045.   Interface</I
  44046. ></SPAN
  44047. >. As the name implies, this <VAR
  44048. CLASS="literal"
  44049. >SAPI</VAR
  44050. > type
  44051.   main focus is on developing shell (or desktop as well) applications with
  44052.   PHP.  There are quite a few differences between the
  44053.   <VAR
  44054. CLASS="literal"
  44055. >CLI SAPI</VAR
  44056. > and other <VAR
  44057. CLASS="literal"
  44058. >SAPI</VAR
  44059. >s which are
  44060.   explained in this chapter.  It's worth mentioning
  44061.   that <VAR
  44062. CLASS="literal"
  44063. >CLI</VAR
  44064. > and <VAR
  44065. CLASS="literal"
  44066. >CGI</VAR
  44067. > are different
  44068.   SAPI's although they do share many of the same behaviors.
  44069.  </P
  44070. ><P
  44071. >   The <VAR
  44072. CLASS="literal"
  44073. >CLI SAPI</VAR
  44074. > was released for the first time with
  44075.   PHP 4.2.0, but was still experimental and had
  44076.   to be explicitly enabled with <VAR
  44077. CLASS="option"
  44078. >--enable-cli</VAR
  44079. > when running
  44080.   <B
  44081. CLASS="command"
  44082. >./configure</B
  44083. >.  Since PHP 4.3.0 the
  44084.   <VAR
  44085. CLASS="literal"
  44086. >CLI SAPI</VAR
  44087. > is no longer experimental and the option
  44088.   <VAR
  44089. CLASS="option"
  44090. >--enable-cli</VAR
  44091. > is on by default.  You may use
  44092.   <VAR
  44093. CLASS="option"
  44094. >--disable-cli</VAR
  44095. > to disable it.
  44096.  </P
  44097. ><P
  44098. >   As of PHP 4.3.0, the name, location and existence of the CLI/CGI binaries
  44099.   will differ depending on how PHP is installed on your system.  By default
  44100.   when executing <B
  44101. CLASS="command"
  44102. >make</B
  44103. >, both the CGI and CLI are built and
  44104.   placed as <TT
  44105. CLASS="filename"
  44106. >sapi/cgi/php</TT
  44107. > and <TT
  44108. CLASS="filename"
  44109. >sapi/cli/php</TT
  44110. > 
  44111.   respectively, in your PHP source directory.  You will note that both are
  44112.   named php. What happens during <B
  44113. CLASS="command"
  44114. >make install</B
  44115. > depends on
  44116.   your configure line.  If a module SAPI is chosen during configure, such as apxs, or the
  44117.   <VAR
  44118. CLASS="option"
  44119. >--disable-cgi</VAR
  44120. > option is used, the CLI is copied to
  44121.   <TT
  44122. CLASS="filename"
  44123. >{PREFIX}/bin/php</TT
  44124. > during <B
  44125. CLASS="command"
  44126. >make install</B
  44127. >
  44128.   otherwise the CGI is placed there.  So, for example, if <VAR
  44129. CLASS="option"
  44130. >--with--apxs
  44131.   </VAR
  44132. > is in your configure line then the CLI is copied to
  44133.   <TT
  44134. CLASS="filename"
  44135. >{PREFIX}/bin/php</TT
  44136. > during <B
  44137. CLASS="command"
  44138. >make
  44139.   install</B
  44140. >. If you want to override the installation of the CGI
  44141.   binary, use <B
  44142. CLASS="command"
  44143. >make install-cli</B
  44144. > after <B
  44145. CLASS="command"
  44146. >make
  44147.   install</B
  44148. >.  Alternatively you can specify <VAR
  44149. CLASS="option"
  44150. >   --disable-cgi</VAR
  44151. > in your configure line.
  44152.  </P
  44153. ><P
  44154. >   <DIV
  44155. CLASS="note"
  44156. ><BLOCKQUOTE
  44157. CLASS="note"
  44158. ><P
  44159. ><B
  44160. >Note: </B
  44161. >
  44162.     Because both <VAR
  44163. CLASS="option"
  44164. >--enable-cli</VAR
  44165. > and
  44166.     <VAR
  44167. CLASS="option"
  44168. >--enable-cgi</VAR
  44169. > are enabled by default,
  44170.     simply having <VAR
  44171. CLASS="option"
  44172. >--enable-cli</VAR
  44173. > in your
  44174.     configure line does not necessarily mean the CLI will be copied as
  44175.     <TT
  44176. CLASS="filename"
  44177. >{PREFIX}/bin/php</TT
  44178. > during <B
  44179. CLASS="command"
  44180. >make install</B
  44181. >.
  44182.    </P
  44183. ></BLOCKQUOTE
  44184. ></DIV
  44185. >
  44186.  </P
  44187. ><P
  44188. >   The windows packages between PHP 4.2.0 and PHP 4.2.3 distributed the CLI as
  44189.   <TT
  44190. CLASS="filename"
  44191. >php-cli.exe</TT
  44192. >, living in the same folder as the CGI
  44193.   <TT
  44194. CLASS="filename"
  44195. >php.exe</TT
  44196. >. Starting with PHP 4.3.0 the windows package
  44197.   distributes the CLI as <TT
  44198. CLASS="filename"
  44199. >php.exe</TT
  44200. > in a separate folder
  44201.   named <TT
  44202. CLASS="filename"
  44203. >cli</TT
  44204. >, so <TT
  44205. CLASS="filename"
  44206. >cli/php.exe
  44207.   </TT
  44208. >. Starting with PHP 5, the CLI is distributed in the main folder,
  44209.   named  <TT
  44210. CLASS="filename"
  44211. >php.exe</TT
  44212. >. The CGI version is distributed as
  44213.   <TT
  44214. CLASS="filename"
  44215. >php-cgi.exe</TT
  44216. >.
  44217.  </P
  44218. ><P
  44219. >   As of PHP 5, a new <TT
  44220. CLASS="filename"
  44221. >php-win.exe</TT
  44222. > file is distributed.
  44223.   This is equal to the CLI version, except that php-win doesn't output
  44224.   anything and thus provides no console (no "dos box" appears on the screen).
  44225.   This  behavior is similar to php-gtk. You should configure with
  44226.   <VAR
  44227. CLASS="option"
  44228. >--enable-cli-win32</VAR
  44229. >.
  44230.  </P
  44231. ><P
  44232. >   <DIV
  44233. CLASS="note"
  44234. ><BLOCKQUOTE
  44235. CLASS="note"
  44236. ><P
  44237. ><B
  44238. >What SAPI do I have?: </B
  44239. >
  44240.     From a shell, typing <B
  44241. CLASS="command"
  44242. >php -v</B
  44243. > will tell you
  44244.     whether <TT
  44245. CLASS="filename"
  44246. >php</TT
  44247. > is CGI or CLI.  See also the function
  44248.     <A
  44249. HREF="#function.php-sapi-name"
  44250. ><B
  44251. CLASS="function"
  44252. >php_sapi_name()</B
  44253. ></A
  44254. > and the constant <TT
  44255. CLASS="constant"
  44256. ><B
  44257. >     PHP_SAPI</B
  44258. ></TT
  44259. >.
  44260.    </P
  44261. ></BLOCKQUOTE
  44262. ></DIV
  44263. >
  44264.  </P
  44265. ><P
  44266. >   <DIV
  44267. CLASS="note"
  44268. ><BLOCKQUOTE
  44269. CLASS="note"
  44270. ><P
  44271. ><B
  44272. >Note: </B
  44273. >
  44274.     A Unix <VAR
  44275. CLASS="literal"
  44276. >man</VAR
  44277. >ual page was added in PHP 4.3.2.  You may 
  44278.     view this by typing <B
  44279. CLASS="command"
  44280. >man php</B
  44281. > in your shell environment.
  44282.    </P
  44283. ></BLOCKQUOTE
  44284. ></DIV
  44285. >
  44286.  </P
  44287. ><P
  44288. >   Remarkable differences of the <VAR
  44289. CLASS="literal"
  44290. >CLI SAPI</VAR
  44291. > compared to other
  44292.   <VAR
  44293. CLASS="literal"
  44294. >SAPI</VAR
  44295. >s:
  44296.   <P
  44297. ></P
  44298. ><UL
  44299. ><LI
  44300. ><P
  44301. >      Unlike the <VAR
  44302. CLASS="literal"
  44303. >CGI SAPI</VAR
  44304. >, no headers are written to the
  44305.      output.
  44306.     </P
  44307. ><P
  44308. >      Though the <VAR
  44309. CLASS="literal"
  44310. >CGI SAPI</VAR
  44311. > provides a way to suppress HTTP
  44312.      headers, there's no equivalent switch to enable them in the <VAR
  44313. CLASS="literal"
  44314. >CLI
  44315.      SAPI</VAR
  44316. >.
  44317.     </P
  44318. ><P
  44319. >      CLI is started up in quiet mode by default, though the <VAR
  44320. CLASS="option"
  44321. >-q</VAR
  44322. >
  44323.      and <VAR
  44324. CLASS="option"
  44325. >--no-header</VAR
  44326. > switches are kept for compatibility so
  44327.      that you can use older CGI scripts.
  44328.     </P
  44329. ><P
  44330. >      It does not change the working directory to that of the script.
  44331.      (<VAR
  44332. CLASS="option"
  44333. >-C</VAR
  44334. > and <VAR
  44335. CLASS="option"
  44336. >--no-chdir</VAR
  44337. > switches kept for
  44338.      compatibility)
  44339.     </P
  44340. ><P
  44341. >      Plain text error messages (no HTML formatting).
  44342.     </P
  44343. ></LI
  44344. ><LI
  44345. ><P
  44346. >      There are certain <TT
  44347. CLASS="filename"
  44348. >php.ini</TT
  44349. > directives which are overridden by the <VAR
  44350. CLASS="literal"
  44351. >CLI
  44352.      SAPI</VAR
  44353. > because they do not make sense in shell environments:
  44354.     </P
  44355. ><P
  44356. >      <DIV
  44357. CLASS="table"
  44358. ><A
  44359. NAME="AEN7402"
  44360. ></A
  44361. ><P
  44362. ><B
  44363. >Table 43-1. Overridden <TT
  44364. CLASS="filename"
  44365. >php.ini</TT
  44366. > directives</B
  44367. ></P
  44368. ><TABLE
  44369. BORDER="1"
  44370. CLASS="CALSTABLE"
  44371. ><COL><COL><COL><THEAD
  44372. ><TR
  44373. ><TH
  44374. >Directive</TH
  44375. ><TH
  44376. ><VAR
  44377. CLASS="literal"
  44378. >CLI SAPI</VAR
  44379. > default value</TH
  44380. ><TH
  44381. >Comment</TH
  44382. ></TR
  44383. ></THEAD
  44384. ><TBODY
  44385. ><TR
  44386. ><TD
  44387. ><A
  44388. HREF="#ini.html-errors"
  44389. >html_errors</A
  44390. ></TD
  44391. ><TD
  44392. ><TT
  44393. CLASS="constant"
  44394. ><B
  44395. >FALSE</B
  44396. ></TT
  44397. ></TD
  44398. ><TD
  44399. >           It can be quite hard to read the error message in your shell when
  44400.           it's cluttered with all those meaningless <VAR
  44401. CLASS="literal"
  44402. >HTML</VAR
  44403. >
  44404.           tags, therefore this directive defaults to <TT
  44405. CLASS="constant"
  44406. ><B
  44407. >FALSE</B
  44408. ></TT
  44409. >.
  44410.          </TD
  44411. ></TR
  44412. ><TR
  44413. ><TD
  44414. ><A
  44415. HREF="#ini.implicit-flush"
  44416. >implicit_flush</A
  44417. ></TD
  44418. ><TD
  44419. ><TT
  44420. CLASS="constant"
  44421. ><B
  44422. >TRUE</B
  44423. ></TT
  44424. ></TD
  44425. ><TD
  44426. >           It is desired that any output coming from
  44427.           <A
  44428. HREF="#function.print"
  44429. ><B
  44430. CLASS="function"
  44431. >print()</B
  44432. ></A
  44433. >, <A
  44434. HREF="#function.echo"
  44435. ><B
  44436. CLASS="function"
  44437. >echo()</B
  44438. ></A
  44439. > and friends is
  44440.           immediately written to the output and not cached in any buffer. You
  44441.           still can use <A
  44442. HREF="#ref.outcontrol"
  44443. >output buffering</A
  44444. >
  44445.           if you want to defer or manipulate standard output.
  44446.          </TD
  44447. ></TR
  44448. ><TR
  44449. ><TD
  44450. ><A
  44451. HREF="#ini.max-execution-time"
  44452. >max_execution_time</A
  44453. ></TD
  44454. ><TD
  44455. >0 (unlimited)</TD
  44456. ><TD
  44457. >           Due to endless possibilities of using PHP in
  44458.           shell environments, the maximum execution time has been set to
  44459.           unlimited. Whereas applications written for the web are often
  44460.           executed very quickly, shell application tend to have a much
  44461.           longer execution time.
  44462.          </TD
  44463. ></TR
  44464. ><TR
  44465. ><TD
  44466. ><A
  44467. HREF="#ini.register-argc-argv"
  44468. >register_argc_argv</A
  44469. ></TD
  44470. ><TD
  44471. ><TT
  44472. CLASS="constant"
  44473. ><B
  44474. >TRUE</B
  44475. ></TT
  44476. ></TD
  44477. ><TD
  44478. >          <P
  44479. >           Because this setting is <TT
  44480. CLASS="constant"
  44481. ><B
  44482. >TRUE</B
  44483. ></TT
  44484. > you will always have access to
  44485.           <SPAN
  44486. CLASS="emphasis"
  44487. ><I
  44488. CLASS="emphasis"
  44489. >argc</I
  44490. ></SPAN
  44491. > (number of arguments passed to the 
  44492.           application) and <SPAN
  44493. CLASS="emphasis"
  44494. ><I
  44495. CLASS="emphasis"
  44496. >argv</I
  44497. ></SPAN
  44498. > (array of the actual
  44499.           arguments) in the <VAR
  44500. CLASS="literal"
  44501. >CLI SAPI</VAR
  44502. >.
  44503.          </P
  44504. >
  44505.          <P
  44506. >           As of PHP 4.3.0, the PHP variables <VAR
  44507. CLASS="varname"
  44508. >$argc</VAR
  44509. >
  44510.           and <VAR
  44511. CLASS="varname"
  44512. >$argv</VAR
  44513. > are registered and filled in with the appropriate 
  44514.           values when using the <VAR
  44515. CLASS="literal"
  44516. >CLI SAPI</VAR
  44517. >. Prior to this version,
  44518.           the creation of these variables behaved as they do in
  44519.           <VAR
  44520. CLASS="literal"
  44521. >CGI</VAR
  44522. > and <VAR
  44523. CLASS="literal"
  44524. >MODULE</VAR
  44525. > versions
  44526.           which requires the PHP directive
  44527.           <A
  44528. HREF="#ini.register-globals"
  44529. >register_globals</A
  44530. > to
  44531.           be <SPAN
  44532. CLASS="emphasis"
  44533. ><I
  44534. CLASS="emphasis"
  44535. >on</I
  44536. ></SPAN
  44537. >.  Regardless of version or register_globals
  44538.           setting, you can always go through either 
  44539.           <A
  44540. HREF="#reserved.variables.server"
  44541. >$_SERVER</A
  44542. > or 
  44543.           <VAR
  44544. CLASS="varname"
  44545. >$HTTP_SERVER_VARS</VAR
  44546. >.  Example:
  44547.           <VAR
  44548. CLASS="varname"
  44549. >$_SERVER['argv']</VAR
  44550. >
  44551.          </P
  44552. >
  44553.          </TD
  44554. ></TR
  44555. ></TBODY
  44556. ></TABLE
  44557. ></DIV
  44558. >
  44559.     </P
  44560. ><DIV
  44561. CLASS="note"
  44562. ><BLOCKQUOTE
  44563. CLASS="note"
  44564. ><P
  44565. ><B
  44566. >Note: </B
  44567. >
  44568.       These directives cannot be initialized with another value from the
  44569.       configuration file <TT
  44570. CLASS="filename"
  44571. >php.ini</TT
  44572. > or a custom one (if specified). This is a
  44573.       limitation because those default values are applied after all
  44574.       configuration files have been parsed. However, their value can be changed
  44575.       during runtime (which does not make sense for all of those directives,
  44576.       e.g. <A
  44577. HREF="#ini.register-argc-argv"
  44578. >register_argc_argv</A
  44579. >).
  44580.      </P
  44581. ></BLOCKQUOTE
  44582. ></DIV
  44583. ></LI
  44584. ><LI
  44585. ><P
  44586. >      To ease working in the shell environment, the following constants
  44587.      are defined:
  44588.      <DIV
  44589. CLASS="table"
  44590. ><A
  44591. NAME="AEN7463"
  44592. ></A
  44593. ><P
  44594. ><B
  44595. >Table 43-2. CLI specific Constants</B
  44596. ></P
  44597. ><TABLE
  44598. BORDER="1"
  44599. CLASS="CALSTABLE"
  44600. ><COL><COL><THEAD
  44601. ><TR
  44602. ><TH
  44603. >Constant</TH
  44604. ><TH
  44605. >Description</TH
  44606. ></TR
  44607. ></THEAD
  44608. ><TBODY
  44609. ><TR
  44610. ><TD
  44611. ><TT
  44612. CLASS="constant"
  44613. ><B
  44614. >STDIN</B
  44615. ></TT
  44616. ></TD
  44617. ><TD
  44618. >          An already opened stream to <VAR
  44619. CLASS="literal"
  44620. >stdin</VAR
  44621. >. This saves
  44622.          opening it with
  44623.          <TABLE
  44624. BORDER="0"
  44625. BGCOLOR="#E0E0E0"
  44626. CELLPADDING="5"
  44627. ><TR
  44628. ><TD
  44629. ><PRE
  44630. CLASS="php"
  44631. ><?php
  44632.  
  44633. $stdin = fopen('php://stdin', 'r');
  44634.  
  44635. ?></PRE
  44636. ></TD
  44637. ></TR
  44638. ></TABLE
  44639. >
  44640.          If you want to read single line from <VAR
  44641. CLASS="literal"
  44642. >stdin</VAR
  44643. >, you can
  44644.          use
  44645.          <TABLE
  44646. BORDER="0"
  44647. BGCOLOR="#E0E0E0"
  44648. CELLPADDING="5"
  44649. ><TR
  44650. ><TD
  44651. ><PRE
  44652. CLASS="php"
  44653. ><?php
  44654. $line = trim(fgets(STDIN)); // reads one line from STDIN
  44655. fscanf(STDIN, "%d\n", $number); // reads number from STDIN
  44656. ?></PRE
  44657. ></TD
  44658. ></TR
  44659. ></TABLE
  44660. >
  44661.          </TD
  44662. ></TR
  44663. ><TR
  44664. ><TD
  44665. ><TT
  44666. CLASS="constant"
  44667. ><B
  44668. >STDOUT</B
  44669. ></TT
  44670. ></TD
  44671. ><TD
  44672. >          An already opened stream to <VAR
  44673. CLASS="literal"
  44674. >stdout</VAR
  44675. >. This saves
  44676.          opening it with
  44677.          <TABLE
  44678. BORDER="0"
  44679. BGCOLOR="#E0E0E0"
  44680. CELLPADDING="5"
  44681. ><TR
  44682. ><TD
  44683. ><PRE
  44684. CLASS="php"
  44685. ><?php
  44686.  
  44687. $stdout = fopen('php://stdout', 'w');
  44688.  
  44689. ?></PRE
  44690. ></TD
  44691. ></TR
  44692. ></TABLE
  44693. >
  44694.          </TD
  44695. ></TR
  44696. ><TR
  44697. ><TD
  44698. ><TT
  44699. CLASS="constant"
  44700. ><B
  44701. >STDERR</B
  44702. ></TT
  44703. ></TD
  44704. ><TD
  44705. >          An already opened stream to <VAR
  44706. CLASS="literal"
  44707. >stderr</VAR
  44708. >. This saves
  44709.          opening it with
  44710.          <TABLE
  44711. BORDER="0"
  44712. BGCOLOR="#E0E0E0"
  44713. CELLPADDING="5"
  44714. ><TR
  44715. ><TD
  44716. ><PRE
  44717. CLASS="php"
  44718. ><?php
  44719.  
  44720. $stderr = fopen('php://stderr', 'w');
  44721.  
  44722. ?></PRE
  44723. ></TD
  44724. ></TR
  44725. ></TABLE
  44726. >
  44727.          </TD
  44728. ></TR
  44729. ></TBODY
  44730. ></TABLE
  44731. ></DIV
  44732. >
  44733.     </P
  44734. ><P
  44735. >      Given the above, you don't need to open e.g. a stream for
  44736.      <VAR
  44737. CLASS="literal"
  44738. >stderr</VAR
  44739. > yourself but simply use the constant instead of
  44740.      the stream resource:
  44741.      <TABLE
  44742. BORDER="0"
  44743. BGCOLOR="#E0E0E0"
  44744. CELLPADDING="5"
  44745. ><TR
  44746. ><TD
  44747. ><PRE
  44748. CLASS="shell"
  44749. >php -r 'fwrite(STDERR, "stderr\n");'</PRE
  44750. ></TD
  44751. ></TR
  44752. ></TABLE
  44753. >
  44754.      You do not need to explicitly close these streams, as they are closed
  44755.      automatically by PHP when your script ends.
  44756.     </P
  44757. ></LI
  44758. ><LI
  44759. ><P
  44760. >      The <VAR
  44761. CLASS="literal"
  44762. >CLI SAPI</VAR
  44763. > does <SPAN
  44764. CLASS="strong"
  44765. ><B
  44766. CLASS="emphasis"
  44767. >not</B
  44768. ></SPAN
  44769. > change the current directory to the directory
  44770.      of the executed script!
  44771.     </P
  44772. ><P
  44773. >      Example showing the difference to the <VAR
  44774. CLASS="literal"
  44775. >CGI SAPI</VAR
  44776. >:
  44777.      <TABLE
  44778. BORDER="0"
  44779. BGCOLOR="#E0E0E0"
  44780. CELLPADDING="5"
  44781. ><TR
  44782. ><TD
  44783. ><PRE
  44784. CLASS="php"
  44785. ><?php
  44786. // Our simple test application named test.php
  44787. echo getcwd(), "\n";
  44788. ?></PRE
  44789. ></TD
  44790. ></TR
  44791. ></TABLE
  44792. >
  44793.     </P
  44794. ><P
  44795. >      When using the <VAR
  44796. CLASS="literal"
  44797. >CGI</VAR
  44798. > version, the output is:
  44799.      <TABLE
  44800. BORDER="0"
  44801. BGCOLOR="#E0E0E0"
  44802. CELLPADDING="5"
  44803. ><TR
  44804. ><TD
  44805. ><PRE
  44806. CLASS="screen"
  44807. >$ pwd
  44808. /tmp
  44809.  
  44810. $ php -q another_directory/test.php
  44811. /tmp/another_directory</PRE
  44812. ></TD
  44813. ></TR
  44814. ></TABLE
  44815. >
  44816.      This clearly shows that PHP changes its current
  44817.      directory to the one of the executed script.
  44818.     </P
  44819. ><P
  44820. >      Using the <VAR
  44821. CLASS="literal"
  44822. >CLI SAPI</VAR
  44823. > yields:
  44824.      <TABLE
  44825. BORDER="0"
  44826. BGCOLOR="#E0E0E0"
  44827. CELLPADDING="5"
  44828. ><TR
  44829. ><TD
  44830. ><PRE
  44831. CLASS="screen"
  44832. >$ pwd
  44833. /tmp
  44834.  
  44835. $ php -f another_directory/test.php
  44836. /tmp</PRE
  44837. ></TD
  44838. ></TR
  44839. ></TABLE
  44840. >
  44841.      This allows greater flexibility when writing shell tools in
  44842.      PHP.
  44843.     </P
  44844. ><DIV
  44845. CLASS="note"
  44846. ><BLOCKQUOTE
  44847. CLASS="note"
  44848. ><P
  44849. ><B
  44850. >Note: </B
  44851. >
  44852.       The <VAR
  44853. CLASS="literal"
  44854. >CGI SAPI</VAR
  44855. > supports this <VAR
  44856. CLASS="literal"
  44857. >CLI SAPI</VAR
  44858. >
  44859.       behaviour by means of the <VAR
  44860. CLASS="option"
  44861. >-C</VAR
  44862. > switch when run from the
  44863.       command line.
  44864.      </P
  44865. ></BLOCKQUOTE
  44866. ></DIV
  44867. ></LI
  44868. ></UL
  44869. >
  44870.  </P
  44871. ><P
  44872. >   The list of command line options provided by the PHP
  44873.   binary can be queried anytime by running PHP with the
  44874.   <VAR
  44875. CLASS="option"
  44876. >-h</VAR
  44877. > switch:
  44878.   <TABLE
  44879. BORDER="0"
  44880. BGCOLOR="#E0E0E0"
  44881. CELLPADDING="5"
  44882. ><TR
  44883. ><TD
  44884. ><PRE
  44885. CLASS="screen"
  44886. >Usage: php [options] [-f] <file> [args...]
  44887.        php [options] -r <code> [args...]
  44888.        php [options] [-- args...]
  44889.   -s               Display colour syntax highlighted source.
  44890.   -w               Display source with stripped comments and whitespace.
  44891.   -f <file>        Parse <file>.
  44892.   -v               Version number
  44893.   -c <path>|<file> Look for php.ini file in this directory
  44894.   -a               Run interactively
  44895.   -d foo[=bar]     Define INI entry foo with value 'bar'
  44896.   -e               Generate extended information for debugger/profiler
  44897.   -z <file>        Load Zend extension <file>.
  44898.   -l               Syntax check only (lint)
  44899.   -m               Show compiled in modules
  44900.   -i               PHP information
  44901.   -r <code>        Run PHP <code> without using script tags <?..?>
  44902.   -h               This help
  44903.  
  44904.   args...          Arguments passed to script. Use -- args when first argument 
  44905.                    starts with - or script is read from stdin</PRE
  44906. ></TD
  44907. ></TR
  44908. ></TABLE
  44909. >
  44910.  </P
  44911. ><P
  44912. >   The <VAR
  44913. CLASS="literal"
  44914. >CLI SAPI</VAR
  44915. > has three different ways of getting the
  44916.   PHP code you want to execute:
  44917.   <P
  44918. ></P
  44919. ><OL
  44920. TYPE="1"
  44921. ><LI
  44922. ><P
  44923. >      Telling PHP to execute a certain file.
  44924.     </P
  44925. ><P
  44926. >      <TABLE
  44927. BORDER="0"
  44928. BGCOLOR="#E0E0E0"
  44929. CELLPADDING="5"
  44930. ><TR
  44931. ><TD
  44932. ><PRE
  44933. CLASS="screen"
  44934. >php my_script.php
  44935.  
  44936. php -f my_script.php</PRE
  44937. ></TD
  44938. ></TR
  44939. ></TABLE
  44940. >
  44941.      Both ways (whether using the <VAR
  44942. CLASS="option"
  44943. >-f</VAR
  44944. > switch or not) execute
  44945.      the file <TT
  44946. CLASS="filename"
  44947. >my_script.php</TT
  44948. >. You can choose any file to
  44949.      execute - your PHP scripts do not have to end with the
  44950.      <VAR
  44951. CLASS="literal"
  44952. >.php</VAR
  44953. > extension but can have any name or extension
  44954.      you wish.
  44955.     </P
  44956. ></LI
  44957. ><LI
  44958. ><P
  44959. >      Pass the PHP code to execute directly on the command
  44960.      line.
  44961.     </P
  44962. ><P
  44963. >      <TABLE
  44964. BORDER="0"
  44965. BGCOLOR="#E0E0E0"
  44966. CELLPADDING="5"
  44967. ><TR
  44968. ><TD
  44969. ><PRE
  44970. CLASS="screen"
  44971. >php -r 'print_r(get_defined_constants());'</PRE
  44972. ></TD
  44973. ></TR
  44974. ></TABLE
  44975. >
  44976.      Special care has to be taken in regards of shell variable substitution and
  44977.      quoting usage.
  44978.     </P
  44979. ><DIV
  44980. CLASS="note"
  44981. ><BLOCKQUOTE
  44982. CLASS="note"
  44983. ><P
  44984. ><B
  44985. >Note: </B
  44986. >
  44987.       Read the example carefully, there are no beginning or ending tags! The
  44988.       <VAR
  44989. CLASS="option"
  44990. >-r</VAR
  44991. > switch simply does not need them. Using them will
  44992.       lead to a parser error.
  44993.      </P
  44994. ></BLOCKQUOTE
  44995. ></DIV
  44996. ></LI
  44997. ><LI
  44998. ><P
  44999. >      Provide the PHP code to execute via standard input
  45000.      (<VAR
  45001. CLASS="literal"
  45002. >stdin</VAR
  45003. >).
  45004.     </P
  45005. ><P
  45006. >      This gives the powerful ability to dynamically create
  45007.      PHP code and feed it to the binary, as shown in this
  45008.      (fictional) example:
  45009.      <TABLE
  45010. BORDER="0"
  45011. BGCOLOR="#E0E0E0"
  45012. CELLPADDING="5"
  45013. ><TR
  45014. ><TD
  45015. ><PRE
  45016. CLASS="screen"
  45017. >$ some_application | some_filter | php | sort -u >final_output.txt</PRE
  45018. ></TD
  45019. ></TR
  45020. ></TABLE
  45021. >
  45022.     </P
  45023. ></LI
  45024. ></OL
  45025. >
  45026.   You cannot combine any of the three ways to execute code.
  45027.  </P
  45028. ><P
  45029. >   Like every shell application, the PHP binary
  45030.   accepts a number of arguments but your PHP script can
  45031.   also receive arguments. The number of arguments which can be passed to your script
  45032.   is not limited by PHP (the shell has a certain size limit
  45033.   in the number of characters which can be passed; usually you won't hit this
  45034.   limit). The arguments passed to your script are available in the global
  45035.   array <VAR
  45036. CLASS="varname"
  45037. >$argv</VAR
  45038. >. The zero index always contains the script
  45039.   name (which is <VAR
  45040. CLASS="literal"
  45041. >-</VAR
  45042. > in case the PHP code
  45043.   is coming from either standard input or from the command line switch
  45044.   <VAR
  45045. CLASS="option"
  45046. >-r</VAR
  45047. >). The second registered global variable is
  45048.   <VAR
  45049. CLASS="varname"
  45050. >$argc</VAR
  45051. > which contains the number of elements in the
  45052.   <VAR
  45053. CLASS="varname"
  45054. >$argv</VAR
  45055. > array (<SPAN
  45056. CLASS="strong"
  45057. ><B
  45058. CLASS="emphasis"
  45059. >not</B
  45060. ></SPAN
  45061. > the
  45062.   number of arguments passed to the script).
  45063.  </P
  45064. ><P
  45065. >   As long as the arguments you want to pass to your script do not start with
  45066.   the <VAR
  45067. CLASS="literal"
  45068. >-</VAR
  45069. > character, there's nothing special to watch out
  45070.   for. Passing an argument to your script which starts with a
  45071.    <VAR
  45072. CLASS="literal"
  45073. >-</VAR
  45074. > will cause trouble because PHP
  45075.    itself thinks it has to handle it. To prevent this, use the argument list
  45076.    separator <VAR
  45077. CLASS="literal"
  45078. >--</VAR
  45079. >. After this separator has been parsed by
  45080.    PHP, every argument following it is passed
  45081.    untouched to your script.
  45082.  </P
  45083. ><P
  45084. >   <TABLE
  45085. BORDER="0"
  45086. BGCOLOR="#E0E0E0"
  45087. CELLPADDING="5"
  45088. ><TR
  45089. ><TD
  45090. ><PRE
  45091. CLASS="screen"
  45092. ># This will not execute the given code but will show the PHP usage
  45093. $ php -r 'var_dump($argv);' -h
  45094. Usage: php [options] [-f] <file> [args...]
  45095. [...]
  45096.  
  45097. # This will pass the '-h' argument to your script and prevent PHP from showing it's usage
  45098. $ php -r 'var_dump($argv);' -- -h
  45099. array(2) {
  45100.   [0]=>
  45101.   string(1) "-"
  45102.   [1]=>
  45103.   string(2) "-h"
  45104. }</PRE
  45105. ></TD
  45106. ></TR
  45107. ></TABLE
  45108. >
  45109.  </P
  45110. ><P
  45111. >   However, there's another way of using PHP for shell
  45112.   scripting. You can write a script where the first line starts with
  45113.   <VAR
  45114. CLASS="literal"
  45115. >#!/usr/bin/php</VAR
  45116. >. Following this you can place
  45117.   normal PHP code included within the PHP
  45118.   starting and end tags. Once you have set the execution attributes of the file
  45119.   appropriately (e.g. <B
  45120. CLASS="command"
  45121. >chmod +x test</B
  45122. >) your script can be
  45123.   executed like a normal shell or perl script:
  45124.   <TABLE
  45125. BORDER="0"
  45126. BGCOLOR="#E0E0E0"
  45127. CELLPADDING="5"
  45128. ><TR
  45129. ><TD
  45130. ><PRE
  45131. CLASS="php"
  45132. >#!/usr/bin/php
  45133. <?php
  45134. var_dump($argv);
  45135. ?></PRE
  45136. ></TD
  45137. ></TR
  45138. ></TABLE
  45139. >
  45140.   Assuming this file is named <TT
  45141. CLASS="filename"
  45142. >test</TT
  45143. > in the current
  45144.   directory, we can now do the following:
  45145.   <TABLE
  45146. BORDER="0"
  45147. BGCOLOR="#E0E0E0"
  45148. CELLPADDING="5"
  45149. ><TR
  45150. ><TD
  45151. ><PRE
  45152. CLASS="screen"
  45153. >$ chmod +x test
  45154. $ ./test -h -- foo
  45155. array(4) {
  45156.   [0]=>
  45157.   string(6) "./test"
  45158.   [1]=>
  45159.   string(2) "-h"
  45160.   [2]=>
  45161.   string(2) "--"
  45162.   [3]=>
  45163.   string(3) "foo"
  45164. }</PRE
  45165. ></TD
  45166. ></TR
  45167. ></TABLE
  45168. >
  45169.   As you see, in this case no care needs to be taken when passing parameters
  45170.   which start with <VAR
  45171. CLASS="literal"
  45172. >-</VAR
  45173. > to your script.
  45174.  </P
  45175. ><P
  45176. >   Long options are available since PHP 4.3.3.
  45177.   <DIV
  45178. CLASS="table"
  45179. ><A
  45180. NAME="AEN7558"
  45181. ></A
  45182. ><P
  45183. ><B
  45184. >Table 43-3. Command line options</B
  45185. ></P
  45186. ><TABLE
  45187. BORDER="1"
  45188. CLASS="CALSTABLE"
  45189. ><COL><COL><THEAD
  45190. ><TR
  45191. ><TH
  45192. >Option</TH
  45193. ><TH
  45194. >Long Option</TH
  45195. ><TH
  45196. >Description</TH
  45197. ></TR
  45198. ></THEAD
  45199. ><TBODY
  45200. ><TR
  45201. ><TD
  45202. >-s</TD
  45203. ><TD
  45204. >--syntax-highlight</TD
  45205. ><TD
  45206. >        <P
  45207. >         Display colour syntax highlighted source.
  45208.        </P
  45209. >
  45210.        <P
  45211. >         This option uses the internal mechanism to parse the file and produces
  45212.         a <VAR
  45213. CLASS="literal"
  45214. >HTML</VAR
  45215. > highlighted version of it and writes it to
  45216.         standard output. Note that all it does it to generate a block of
  45217.         <VAR
  45218. CLASS="literal"
  45219. ><code> [...] </code></VAR
  45220. >
  45221.         <VAR
  45222. CLASS="literal"
  45223. >HTML</VAR
  45224. > tags, no <VAR
  45225. CLASS="literal"
  45226. >HTML</VAR
  45227. > headers.
  45228.        </P
  45229. >
  45230.        <DIV
  45231. CLASS="note"
  45232. ><BLOCKQUOTE
  45233. CLASS="note"
  45234. ><P
  45235. ><B
  45236. >Note: </B
  45237. >
  45238.          This option does not work together with the <VAR
  45239. CLASS="option"
  45240. >-r</VAR
  45241. >
  45242.          option.
  45243.         </P
  45244. ></BLOCKQUOTE
  45245. ></DIV
  45246. >
  45247.       </TD
  45248. ></TR
  45249. ><TR
  45250. ><TD
  45251. >-s</TD
  45252. ><TD
  45253. >--syntax-highlighting</TD
  45254. ><TD
  45255. >        <P
  45256. >         Alias of <VAR
  45257. CLASS="option"
  45258. >--syntax-highlight</VAR
  45259. >.
  45260.        </P
  45261. >
  45262.       </TD
  45263. ></TR
  45264. ><TR
  45265. ><TD
  45266. >-w</TD
  45267. ><TD
  45268. >--strip</TD
  45269. ><TD
  45270. >        <P
  45271. >         Display source with stripped comments and whitespace.
  45272.        </P
  45273. >
  45274.        <DIV
  45275. CLASS="note"
  45276. ><BLOCKQUOTE
  45277. CLASS="note"
  45278. ><P
  45279. ><B
  45280. >Note: </B
  45281. >
  45282.          This option does not work together with the <VAR
  45283. CLASS="option"
  45284. >-r</VAR
  45285. >
  45286.          option.
  45287.         </P
  45288. ></BLOCKQUOTE
  45289. ></DIV
  45290. >
  45291.       </TD
  45292. ></TR
  45293. ><TR
  45294. ><TD
  45295. >-f</TD
  45296. ><TD
  45297. >--file</TD
  45298. ><TD
  45299. >        <P
  45300. >         Parses and executed the given filename to the <VAR
  45301. CLASS="option"
  45302. >-f</VAR
  45303. >
  45304.         option. This switch is optional and can be left out. Only providing
  45305.         the filename to execute is sufficient.
  45306.        </P
  45307. >
  45308.       </TD
  45309. ></TR
  45310. ><TR
  45311. ><TD
  45312. >-v</TD
  45313. ><TD
  45314. >--version</TD
  45315. ><TD
  45316. >        <P
  45317. >         Writes the PHP, PHP SAPI, and Zend version to standard output, e.g.
  45318.         <TABLE
  45319. BORDER="0"
  45320. BGCOLOR="#E0E0E0"
  45321. CELLPADDING="5"
  45322. ><TR
  45323. ><TD
  45324. ><PRE
  45325. CLASS="screen"
  45326. >$ php -v
  45327. PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
  45328. Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies</PRE
  45329. ></TD
  45330. ></TR
  45331. ></TABLE
  45332. >
  45333.        </P
  45334. >
  45335.       </TD
  45336. ></TR
  45337. ><TR
  45338. ><TD
  45339. >-c</TD
  45340. ><TD
  45341. >--php-ini</TD
  45342. ><TD
  45343. >        <P
  45344. >         With this option one can either specify a directory where to look for
  45345.         <TT
  45346. CLASS="filename"
  45347. >php.ini</TT
  45348. > or you can specify a custom <VAR
  45349. CLASS="literal"
  45350. >INI</VAR
  45351. > file
  45352.         directly (which does not need to be named <TT
  45353. CLASS="filename"
  45354. >php.ini</TT
  45355. >), e.g.:
  45356.         <TABLE
  45357. BORDER="0"
  45358. BGCOLOR="#E0E0E0"
  45359. CELLPADDING="5"
  45360. ><TR
  45361. ><TD
  45362. ><PRE
  45363. CLASS="screen"
  45364. >$ php -c /custom/directory/ my_script.php
  45365.  
  45366. $ php -c /custom/directory/custom-file.ini my_script.php</PRE
  45367. ></TD
  45368. ></TR
  45369. ></TABLE
  45370. >
  45371.         If you don't specify this option, file is searched in
  45372.         <A
  45373. HREF="#configuration.file"
  45374. >default locations</A
  45375. >.
  45376.        </P
  45377. >
  45378.       </TD
  45379. ></TR
  45380. ><TR
  45381. ><TD
  45382. >-n</TD
  45383. ><TD
  45384. >--no-php-ini</TD
  45385. ><TD
  45386. >        <P
  45387. >         Ignore <TT
  45388. CLASS="filename"
  45389. >php.ini</TT
  45390. > at all. This switch is available since PHP 4.3.0.
  45391.        </P
  45392. >
  45393.       </TD
  45394. ></TR
  45395. ><TR
  45396. ><TD
  45397. >-d</TD
  45398. ><TD
  45399. >--define</TD
  45400. ><TD
  45401. >        <P
  45402. >         This option allows you to set a custom value for any of the configuration
  45403.         directives allowed in <TT
  45404. CLASS="filename"
  45405. >php.ini</TT
  45406. >. The syntax is:
  45407.         <TABLE
  45408. BORDER="0"
  45409. BGCOLOR="#E0E0E0"
  45410. CELLPADDING="5"
  45411. ><TR
  45412. ><TD
  45413. ><PRE
  45414. CLASS="screen"
  45415. >-d configuration_directive[=value]</PRE
  45416. ></TD
  45417. ></TR
  45418. ></TABLE
  45419. >
  45420.        </P
  45421. >
  45422.        <P
  45423. >         Examples (lines are wrapped for layout reasons):
  45424.         <TABLE
  45425. BORDER="0"
  45426. BGCOLOR="#E0E0E0"
  45427. CELLPADDING="5"
  45428. ><TR
  45429. ><TD
  45430. ><PRE
  45431. CLASS="screen"
  45432. ># Omitting the value part will set the given configuration directive to "1"
  45433. $ php -d max_execution_time
  45434.         -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
  45435. string(1) "1"
  45436.  
  45437. # Passing an empty value part will set the configuration directive to ""
  45438. php -d max_execution_time=
  45439.         -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
  45440. string(0) ""
  45441.  
  45442. # The configuration directive will be set to anything passed after the '=' character
  45443. $  php -d max_execution_time=20
  45444.         -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
  45445. string(2) "20"
  45446. $  php
  45447.         -d max_execution_time=doesntmakesense
  45448.         -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
  45449. string(15) "doesntmakesense"</PRE
  45450. ></TD
  45451. ></TR
  45452. ></TABLE
  45453. >
  45454.        </P
  45455. >
  45456.       </TD
  45457. ></TR
  45458. ><TR
  45459. ><TD
  45460. >-a</TD
  45461. ><TD
  45462. >--interactive</TD
  45463. ><TD
  45464. >        <P
  45465. >         Runs PHP interactively.
  45466.         
  45467.        </P
  45468. >
  45469.       </TD
  45470. ></TR
  45471. ><TR
  45472. ><TD
  45473. >-e</TD
  45474. ><TD
  45475. >--profile-info</TD
  45476. ><TD
  45477. >        <P
  45478. >         Generate extended information for debugger/profiler.
  45479.         
  45480.        </P
  45481. >
  45482.       </TD
  45483. ></TR
  45484. ><TR
  45485. ><TD
  45486. >-z</TD
  45487. ><TD
  45488. >--zend-extension</TD
  45489. ><TD
  45490. >        <P
  45491. >         Load Zend extension. If only a filename is given, PHP tries to load
  45492.         this extension from the current default library path on your system
  45493.         (usually specified <TT
  45494. CLASS="filename"
  45495. >/etc/ld.so.conf</TT
  45496. > on Linux
  45497.         systems).  Passing a filename with an absolute path information will
  45498.         not use the systems library search path. A relative filename with a
  45499.         directory information will tell PHP only to try to
  45500.         load the extension relative to the current directory.
  45501.        </P
  45502. >
  45503.       </TD
  45504. ></TR
  45505. ><TR
  45506. ><TD
  45507. >-l</TD
  45508. ><TD
  45509. >--syntax-check</TD
  45510. ><TD
  45511. >        <P
  45512. >         This option provides a convenient way to only perform a syntax check
  45513.         on the given PHP code. On success, the text
  45514.         <VAR
  45515. CLASS="literal"
  45516. >No syntax errors detected in <filename></VAR
  45517. > is
  45518.         written to standard output and the shell return code is
  45519.         <VAR
  45520. CLASS="literal"
  45521. >0</VAR
  45522. >. On failure, the text <VAR
  45523. CLASS="literal"
  45524. >Errors parsing
  45525.         <filename></VAR
  45526. > in addition to the internal parser error
  45527.         message is written to standard output and the shell return code is set
  45528.         to <VAR
  45529. CLASS="literal"
  45530. >255</VAR
  45531. >.
  45532.        </P
  45533. >
  45534.        <P
  45535. >         This option won't find fatal errors (like undefined functions). Use
  45536.         <VAR
  45537. CLASS="option"
  45538. >-f</VAR
  45539. > if you would like to test for fatal errors too.
  45540.        </P
  45541. >
  45542.        <DIV
  45543. CLASS="note"
  45544. ><BLOCKQUOTE
  45545. CLASS="note"
  45546. ><P
  45547. ><B
  45548. >Note: </B
  45549. >
  45550.          This option does not work together with the <VAR
  45551. CLASS="option"
  45552. >-r</VAR
  45553. >
  45554.          option.
  45555.         </P
  45556. ></BLOCKQUOTE
  45557. ></DIV
  45558. >
  45559.       </TD
  45560. ></TR
  45561. ><TR
  45562. ><TD
  45563. >-m</TD
  45564. ><TD
  45565. >--modules</TD
  45566. ><TD
  45567. >        <P
  45568. >         Using this option, PHP prints out the built in (and loaded) PHP and
  45569.         Zend modules:
  45570.         <TABLE
  45571. BORDER="0"
  45572. BGCOLOR="#E0E0E0"
  45573. CELLPADDING="5"
  45574. ><TR
  45575. ><TD
  45576. ><PRE
  45577. CLASS="screen"
  45578. >$ php -m
  45579. [PHP Modules]
  45580. xml
  45581. tokenizer
  45582. standard
  45583. session
  45584. posix
  45585. pcre
  45586. overload
  45587. mysql
  45588. mbstring
  45589. ctype
  45590.  
  45591. [Zend Modules]</PRE
  45592. ></TD
  45593. ></TR
  45594. ></TABLE
  45595. >
  45596.        </P
  45597. >
  45598.       </TD
  45599. ></TR
  45600. ><TR
  45601. ><TD
  45602. >-i</TD
  45603. ><TD
  45604. >--info</TD
  45605. ><TD
  45606. >        This command line option calls <A
  45607. HREF="#function.phpinfo"
  45608. ><B
  45609. CLASS="function"
  45610. >phpinfo()</B
  45611. ></A
  45612. >, and prints
  45613.        out the results. If PHP is not working correctly, it is
  45614.        advisable to use <B
  45615. CLASS="command"
  45616. >php -i</B
  45617. > and see whether any error
  45618.        messages are printed out before or in place of the information tables.
  45619.        Beware that when using the CGI mode the output is in <VAR
  45620. CLASS="literal"
  45621. >HTML</VAR
  45622. > 
  45623.        and therefore quite huge.
  45624.       </TD
  45625. ></TR
  45626. ><TR
  45627. ><TD
  45628. >-r</TD
  45629. ><TD
  45630. >--run</TD
  45631. ><TD
  45632. >        <P
  45633. >         This option allows execution of PHP right from
  45634.         within the command line. The PHP start and end tags
  45635.         (<VAR
  45636. CLASS="literal"
  45637. ><?php</VAR
  45638. > and <VAR
  45639. CLASS="literal"
  45640. >?></VAR
  45641. >) are
  45642.         <SPAN
  45643. CLASS="strong"
  45644. ><B
  45645. CLASS="emphasis"
  45646. >not needed</B
  45647. ></SPAN
  45648. > and will cause a parser
  45649.         error if present.
  45650.        </P
  45651. >
  45652.        <DIV
  45653. CLASS="note"
  45654. ><BLOCKQUOTE
  45655. CLASS="note"
  45656. ><P
  45657. ><B
  45658. >Note: </B
  45659. >
  45660.          Care has to be taken when using this form of PHP
  45661.          to not collide with command line variable substitution done by the
  45662.          shell.
  45663.         </P
  45664. ><P
  45665. >          Example showing a parser error
  45666.          <TABLE
  45667. BORDER="0"
  45668. BGCOLOR="#E0E0E0"
  45669. CELLPADDING="5"
  45670. ><TR
  45671. ><TD
  45672. ><PRE
  45673. CLASS="screen"
  45674. >$ php -r "$foo = get_defined_constants();"
  45675. Command line code(1) : Parse error - parse error, unexpected '='</PRE
  45676. ></TD
  45677. ></TR
  45678. ></TABLE
  45679. >
  45680.          The problem here is that the sh/bash performs variable substitution
  45681.          even when using double quotes <VAR
  45682. CLASS="literal"
  45683. >"</VAR
  45684. >. Since the
  45685.          variable <VAR
  45686. CLASS="varname"
  45687. >$foo</VAR
  45688. > is unlikely to be defined, it
  45689.          expands to nothing which results in the code passed to
  45690.          PHP for execution actually reading:
  45691.          <TABLE
  45692. BORDER="0"
  45693. BGCOLOR="#E0E0E0"
  45694. CELLPADDING="5"
  45695. ><TR
  45696. ><TD
  45697. ><PRE
  45698. CLASS="screen"
  45699. >$ php -r " = get_defined_constants();"</PRE
  45700. ></TD
  45701. ></TR
  45702. ></TABLE
  45703. >
  45704.          The correct way would be to use single quotes <VAR
  45705. CLASS="literal"
  45706. >'</VAR
  45707. >.
  45708.          Variables in single-quoted strings are not expanded
  45709.          by sh/bash.
  45710.          <TABLE
  45711. BORDER="0"
  45712. BGCOLOR="#E0E0E0"
  45713. CELLPADDING="5"
  45714. ><TR
  45715. ><TD
  45716. ><PRE
  45717. CLASS="screen"
  45718. >$ php -r '$foo = get_defined_constants(); var_dump($foo);'
  45719. array(370) {
  45720.   ["E_ERROR"]=>
  45721.   int(1)
  45722.   ["E_WARNING"]=>
  45723.   int(2)
  45724.   ["E_PARSE"]=>
  45725.   int(4)
  45726.   ["E_NOTICE"]=>
  45727.   int(8)
  45728.   ["E_CORE_ERROR"]=>
  45729.   [...]</PRE
  45730. ></TD
  45731. ></TR
  45732. ></TABLE
  45733. >
  45734.          If you are using a shell different from sh/bash, you might experience
  45735.          further issues. Feel free to open a bug report at
  45736.          <A
  45737. HREF="http://bugs.php.net/"
  45738. TARGET="_top"
  45739. >http://bugs.php.net/</A
  45740. > or send a mail to
  45741.          phpdoc@lists.php.net.
  45742.  
  45743.          One can still easily run into troubles when trying to get shell
  45744.          variables into the code or using backslashes for escaping. You've
  45745.          been warned. 
  45746.         </P
  45747. ></BLOCKQUOTE
  45748. ></DIV
  45749. >
  45750.        <DIV
  45751. CLASS="note"
  45752. ><BLOCKQUOTE
  45753. CLASS="note"
  45754. ><P
  45755. ><B
  45756. >Note: </B
  45757. >
  45758.          <VAR
  45759. CLASS="option"
  45760. >-r</VAR
  45761. > is available in the <SPAN
  45762. CLASS="emphasis"
  45763. ><I
  45764. CLASS="emphasis"
  45765. >CLI</I
  45766. ></SPAN
  45767. >
  45768.          SAPI and not in the <SPAN
  45769. CLASS="emphasis"
  45770. ><I
  45771. CLASS="emphasis"
  45772. >CGI</I
  45773. ></SPAN
  45774. > SAPI.
  45775.         </P
  45776. ></BLOCKQUOTE
  45777. ></DIV
  45778. >
  45779.       </TD
  45780. ></TR
  45781. ><TR
  45782. ><TD
  45783. >-h</TD
  45784. ><TD
  45785. >--help</TD
  45786. ><TD
  45787. >        With this option, you can get information about the actual list of
  45788.        command line options and some one line descriptions about what they do.
  45789.       </TD
  45790. ></TR
  45791. ><TR
  45792. ><TD
  45793. >-?</TD
  45794. ><TD
  45795. >--usage</TD
  45796. ><TD
  45797. >        Alias of <VAR
  45798. CLASS="option"
  45799. >--help</VAR
  45800. >.
  45801.       </TD
  45802. ></TR
  45803. ></TBODY
  45804. ></TABLE
  45805. ></DIV
  45806. >
  45807.  </P
  45808. ><P
  45809. >   The PHP executable can be used to run PHP scripts absolutely independent
  45810.   from the web server. If you are on a Unix system, you should add a special
  45811.   first line to your PHP script, and make it executable, so the system will
  45812.   know, what program should run the script. On a Windows platform you can
  45813.   associate <TT
  45814. CLASS="filename"
  45815. >php.exe</TT
  45816. > with the double click option of the
  45817.   <VAR
  45818. CLASS="literal"
  45819. >.php</VAR
  45820. > files, or you can make a batch
  45821.   file to run the script through PHP. The first line added to the script to
  45822.   work on Unix won't hurt on Windows, so you can write cross platform programs
  45823.   this way. A simple example of writing a command line PHP program can be
  45824.   found below.
  45825.  </P
  45826. ><P
  45827. >   <TABLE
  45828. WIDTH="100%"
  45829. BORDER="0"
  45830. CELLPADDING="0"
  45831. CELLSPACING="0"
  45832. CLASS="EXAMPLE"
  45833. ><TR
  45834. ><TD
  45835. ><DIV
  45836. CLASS="example"
  45837. ><A
  45838. NAME="AEN7710"
  45839. ></A
  45840. ><P
  45841. ><B
  45842. >Example 43-1. Script intended to be run from command line (script.php)</B
  45843. ></P
  45844. ><TABLE
  45845. BORDER="0"
  45846. BGCOLOR="#E0E0E0"
  45847. CELLPADDING="5"
  45848. ><TR
  45849. ><TD
  45850. ><PRE
  45851. CLASS="php"
  45852. >#!/usr/bin/php
  45853. <?php
  45854.  
  45855. if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
  45856. ?>
  45857.  
  45858. This is a command line PHP script with one option.
  45859.  
  45860.   Usage:
  45861.   <?php echo $argv[0]; ?> <option>
  45862.  
  45863.   <option> can be some word you would like
  45864.   to print out. With the --help, -help, -h,
  45865.   or -? options, you can get this help.
  45866.  
  45867. <?php
  45868. } else {
  45869.     echo $argv[1];
  45870. }
  45871. ?></PRE
  45872. ></TD
  45873. ></TR
  45874. ></TABLE
  45875. ></DIV
  45876. ></TD
  45877. ></TR
  45878. ></TABLE
  45879. >
  45880.  </P
  45881. ><P
  45882. >   In the script above, we used the special first line to indicate
  45883.   that this file should be run by PHP. We work with a CLI version
  45884.   here, so there will be no HTTP header printouts. There are two
  45885.   variables you can use while writing command line applications with
  45886.   PHP: <VAR
  45887. CLASS="varname"
  45888. >$argc</VAR
  45889. > and <VAR
  45890. CLASS="varname"
  45891. >$argv</VAR
  45892. >. The
  45893.   first is the number of arguments plus one (the name of the script
  45894.   running). The second is an array containing the arguments, starting
  45895.   with the script name as number zero (<VAR
  45896. CLASS="varname"
  45897. >$argv[0]</VAR
  45898. >).
  45899.  </P
  45900. ><P
  45901. >   In the program above we checked if there are less or more than one
  45902.   arguments. Also if the argument was <VAR
  45903. CLASS="option"
  45904. >--help</VAR
  45905. >,
  45906.   <VAR
  45907. CLASS="option"
  45908. >-help</VAR
  45909. >, <VAR
  45910. CLASS="option"
  45911. >-h</VAR
  45912. > or <VAR
  45913. CLASS="option"
  45914. >-?</VAR
  45915. >,
  45916.   we printed out the help message, printing the script name dynamically.
  45917.   If we received some other argument we echoed that out.
  45918.  </P
  45919. ><P
  45920. >   If you would like to run the above script on Unix, you need to
  45921.   make it executable, and simply call it as
  45922.   <B
  45923. CLASS="command"
  45924. >script.php echothis</B
  45925. > or
  45926.   <B
  45927. CLASS="command"
  45928. >script.php -h</B
  45929. >. On Windows, you can make a
  45930.   batch file for this task:
  45931.  </P
  45932. ><P
  45933. >   <TABLE
  45934. WIDTH="100%"
  45935. BORDER="0"
  45936. CELLPADDING="0"
  45937. CELLSPACING="0"
  45938. CLASS="EXAMPLE"
  45939. ><TR
  45940. ><TD
  45941. ><DIV
  45942. CLASS="example"
  45943. ><A
  45944. NAME="AEN7726"
  45945. ></A
  45946. ><P
  45947. ><B
  45948. >Example 43-2. Batch file to run a command line PHP script (script.bat)</B
  45949. ></P
  45950. ><TABLE
  45951. BORDER="0"
  45952. BGCOLOR="#E0E0E0"
  45953. CELLPADDING="5"
  45954. ><TR
  45955. ><TD
  45956. ><PRE
  45957. CLASS="shell"
  45958. >@c:\php\cli\php.exe script.php %1 %2 %3 %4</PRE
  45959. ></TD
  45960. ></TR
  45961. ></TABLE
  45962. ></DIV
  45963. ></TD
  45964. ></TR
  45965. ></TABLE
  45966. >
  45967.  </P
  45968. ><P
  45969. >   Assuming you named the above program
  45970.   <TT
  45971. CLASS="filename"
  45972. >script.php</TT
  45973. >, and you have your
  45974.   CLI <TT
  45975. CLASS="filename"
  45976. >php.exe</TT
  45977. > in
  45978.   <TT
  45979. CLASS="filename"
  45980. >c:\php\cli\php.exe</TT
  45981. > this batch file
  45982.   will run it for you with your added options:
  45983.   <B
  45984. CLASS="command"
  45985. >script.bat echothis</B
  45986. > or
  45987.   <B
  45988. CLASS="command"
  45989. >script.bat -h</B
  45990. >.
  45991.  </P
  45992. ><P
  45993. >   See also the <A
  45994. HREF="#ref.readline"
  45995. >Readline</A
  45996. >
  45997.   extension documentation for more functions you can use
  45998.   to enhance your command line applications in PHP.
  45999.  </P
  46000. ></DIV
  46001. ></DIV
  46002. ><DIV
  46003. CLASS="PART"
  46004. ><A
  46005. NAME="funcref"
  46006. ></A
  46007. ><DIV
  46008. CLASS="TITLEPAGE"
  46009. ><H1
  46010. CLASS="title"
  46011. >VI. Function Reference</H1
  46012. ><DIV
  46013. CLASS="TOC"
  46014. ><DL
  46015. ><DT
  46016. ><B
  46017. >Table of Contents</B
  46018. ></DT
  46019. ><DT
  46020. >I. <A
  46021. HREF="#ref.apache"
  46022. >Apache-specific Functions</A
  46023. ></DT
  46024. ><DT
  46025. >II. <A
  46026. HREF="#ref.apd"
  46027. >Advanced PHP debugger</A
  46028. ></DT
  46029. ><DT
  46030. >III. <A
  46031. HREF="#ref.array"
  46032. >Array Functions</A
  46033. ></DT
  46034. ><DT
  46035. >IV. <A
  46036. HREF="#ref.aspell"
  46037. >Aspell functions [deprecated]</A
  46038. ></DT
  46039. ><DT
  46040. >V. <A
  46041. HREF="#ref.bc"
  46042. >BCMath Arbitrary Precision Mathematics Functions</A
  46043. ></DT
  46044. ><DT
  46045. >VI. <A
  46046. HREF="#ref.bcompiler"
  46047. >PHP bytecode Compiler</A
  46048. ></DT
  46049. ><DT
  46050. >VII. <A
  46051. HREF="#ref.bzip2"
  46052. >Bzip2 Compression Functions</A
  46053. ></DT
  46054. ><DT
  46055. >VIII. <A
  46056. HREF="#ref.calendar"
  46057. >Calendar Functions</A
  46058. ></DT
  46059. ><DT
  46060. >IX. <A
  46061. HREF="#ref.ccvs"
  46062. >CCVS API Functions [deprecated]</A
  46063. ></DT
  46064. ><DT
  46065. >X. <A
  46066. HREF="#ref.com"
  46067. >COM and .Net (Windows)</A
  46068. ></DT
  46069. ><DT
  46070. >XI. <A
  46071. HREF="#ref.classkit"
  46072. >Classkit Functions</A
  46073. ></DT
  46074. ><DT
  46075. >XII. <A
  46076. HREF="#ref.classobj"
  46077. >Class/Object Functions</A
  46078. ></DT
  46079. ><DT
  46080. >XIII. <A
  46081. HREF="#ref.cpdf"
  46082. >ClibPDF Functions</A
  46083. ></DT
  46084. ><DT
  46085. >XIV. <A
  46086. HREF="#ref.crack"
  46087. >Crack Functions</A
  46088. ></DT
  46089. ><DT
  46090. >XV. <A
  46091. HREF="#ref.curl"
  46092. >CURL, Client URL Library Functions</A
  46093. ></DT
  46094. ><DT
  46095. >XVI. <A
  46096. HREF="#ref.cybercash"
  46097. >Cybercash Payment Functions</A
  46098. ></DT
  46099. ><DT
  46100. >XVII. <A
  46101. HREF="#ref.cyrus"
  46102. >Cyrus IMAP administration Functions</A
  46103. ></DT
  46104. ><DT
  46105. >XVIII. <A
  46106. HREF="#ref.ctype"
  46107. >Character Type Functions</A
  46108. ></DT
  46109. ><DT
  46110. >XIX. <A
  46111. HREF="#ref.dba"
  46112. >Database (dbm-style) Abstraction Layer Functions</A
  46113. ></DT
  46114. ><DT
  46115. >XX. <A
  46116. HREF="#ref.datetime"
  46117. >Date and Time Functions</A
  46118. ></DT
  46119. ><DT
  46120. >XXI. <A
  46121. HREF="#ref.dbase"
  46122. >dBase Functions</A
  46123. ></DT
  46124. ><DT
  46125. >XXII. <A
  46126. HREF="#ref.dbm"
  46127. >DBM Functions [deprecated]</A
  46128. ></DT
  46129. ><DT
  46130. >XXIII. <A
  46131. HREF="#ref.dbx"
  46132. >dbx Functions</A
  46133. ></DT
  46134. ><DT
  46135. >XXIV. <A
  46136. HREF="#ref.dbplus"
  46137. >DB++ Functions</A
  46138. ></DT
  46139. ><DT
  46140. >XXV. <A
  46141. HREF="#ref.dio"
  46142. >Direct IO Functions</A
  46143. ></DT
  46144. ><DT
  46145. >XXVI. <A
  46146. HREF="#ref.dir"
  46147. >Directory Functions</A
  46148. ></DT
  46149. ><DT
  46150. >XXVII. <A
  46151. HREF="#ref.dom"
  46152. >DOM Functions</A
  46153. ></DT
  46154. ><DT
  46155. >XXVIII. <A
  46156. HREF="#ref.domxml"
  46157. >DOM XML Functions</A
  46158. ></DT
  46159. ><DT
  46160. >XXIX. <A
  46161. HREF="#ref.dotnet"
  46162. >.NET Functions</A
  46163. ></DT
  46164. ><DT
  46165. >XXX. <A
  46166. HREF="#ref.errorfunc"
  46167. >Error Handling and Logging Functions</A
  46168. ></DT
  46169. ><DT
  46170. >XXXI. <A
  46171. HREF="#ref.exif"
  46172. >Exif Functions</A
  46173. ></DT
  46174. ><DT
  46175. >XXXII. <A
  46176. HREF="#ref.fam"
  46177. >File Alteration Monitor Functions</A
  46178. ></DT
  46179. ><DT
  46180. >XXXIII. <A
  46181. HREF="#ref.fbsql"
  46182. >FrontBase Functions</A
  46183. ></DT
  46184. ><DT
  46185. >XXXIV. <A
  46186. HREF="#ref.filepro"
  46187. >filePro Functions</A
  46188. ></DT
  46189. ><DT
  46190. >XXXV. <A
  46191. HREF="#ref.filesystem"
  46192. >Filesystem Functions</A
  46193. ></DT
  46194. ><DT
  46195. >XXXVI. <A
  46196. HREF="#ref.fdf"
  46197. >Forms Data Format Functions</A
  46198. ></DT
  46199. ><DT
  46200. >XXXVII. <A
  46201. HREF="#ref.fribidi"
  46202. >FriBiDi Functions</A
  46203. ></DT
  46204. ><DT
  46205. >XXXVIII. <A
  46206. HREF="#ref.ftp"
  46207. >FTP Functions</A
  46208. ></DT
  46209. ><DT
  46210. >XXXIX. <A
  46211. HREF="#ref.funchand"
  46212. >Function Handling Functions</A
  46213. ></DT
  46214. ><DT
  46215. >XL. <A
  46216. HREF="#ref.gettext"
  46217. >Gettext</A
  46218. ></DT
  46219. ><DT
  46220. >XLI. <A
  46221. HREF="#ref.gmp"
  46222. >GMP Functions</A
  46223. ></DT
  46224. ><DT
  46225. >XLII. <A
  46226. HREF="#ref.http"
  46227. >HTTP Functions</A
  46228. ></DT
  46229. ><DT
  46230. >XLIII. <A
  46231. HREF="#ref.hw"
  46232. >Hyperwave Functions</A
  46233. ></DT
  46234. ><DT
  46235. >XLIV. <A
  46236. HREF="#ref.hwapi"
  46237. >Hyperwave API Functions</A
  46238. ></DT
  46239. ><DT
  46240. >XLV. <A
  46241. HREF="#ref.iconv"
  46242. >iconv Functions</A
  46243. ></DT
  46244. ><DT
  46245. >XLVI. <A
  46246. HREF="#ref.image"
  46247. >Image Functions</A
  46248. ></DT
  46249. ><DT
  46250. >XLVII. <A
  46251. HREF="#ref.imap"
  46252. >IMAP, POP3 and NNTP Functions</A
  46253. ></DT
  46254. ><DT
  46255. >XLVIII. <A
  46256. HREF="#ref.ifx"
  46257. >Informix Functions</A
  46258. ></DT
  46259. ><DT
  46260. >XLIX. <A
  46261. HREF="#ref.ibase"
  46262. >Firebird/InterBase Functions</A
  46263. ></DT
  46264. ><DT
  46265. >L. <A
  46266. HREF="#ref.id3"
  46267. >ID3 Functions</A
  46268. ></DT
  46269. ><DT
  46270. >LI. <A
  46271. HREF="#ref.ingres"
  46272. >Ingres II Functions</A
  46273. ></DT
  46274. ><DT
  46275. >LII. <A
  46276. HREF="#ref.ircg"
  46277. >IRC Gateway Functions</A
  46278. ></DT
  46279. ><DT
  46280. >LIII. <A
  46281. HREF="#ref.java"
  46282. >PHP / Java Integration</A
  46283. ></DT
  46284. ><DT
  46285. >LIV. <A
  46286. HREF="#ref.ldap"
  46287. >LDAP Functions</A
  46288. ></DT
  46289. ><DT
  46290. >LV. <A
  46291. HREF="#ref.lzf"
  46292. >LZF Functions</A
  46293. ></DT
  46294. ><DT
  46295. >LVI. <A
  46296. HREF="#ref.mail"
  46297. >Mail Functions</A
  46298. ></DT
  46299. ><DT
  46300. >LVII. <A
  46301. HREF="#ref.mailparse"
  46302. >mailparse Functions</A
  46303. ></DT
  46304. ><DT
  46305. >LVIII. <A
  46306. HREF="#ref.math"
  46307. >Mathematical Functions</A
  46308. ></DT
  46309. ><DT
  46310. >LIX. <A
  46311. HREF="#ref.mbstring"
  46312. >Multibyte String Functions</A
  46313. ></DT
  46314. ><DT
  46315. >LX. <A
  46316. HREF="#ref.mcal"
  46317. >MCAL Functions</A
  46318. ></DT
  46319. ><DT
  46320. >LXI. <A
  46321. HREF="#ref.mcrypt"
  46322. >Mcrypt Encryption Functions</A
  46323. ></DT
  46324. ><DT
  46325. >LXII. <A
  46326. HREF="#ref.mcve"
  46327. >MCVE Payment Functions</A
  46328. ></DT
  46329. ><DT
  46330. >LXIII. <A
  46331. HREF="#ref.memcache"
  46332. >Memcache Functions</A
  46333. ></DT
  46334. ><DT
  46335. >LXIV. <A
  46336. HREF="#ref.mhash"
  46337. >Mhash Functions</A
  46338. ></DT
  46339. ><DT
  46340. >LXV. <A
  46341. HREF="#ref.mime-magic"
  46342. >Mimetype Functions</A
  46343. ></DT
  46344. ><DT
  46345. >LXVI. <A
  46346. HREF="#ref.mssql"
  46347. >Microsoft SQL Server Functions</A
  46348. ></DT
  46349. ><DT
  46350. >LXVII. <A
  46351. HREF="#ref.ming"
  46352. >Ming functions for Flash</A
  46353. ></DT
  46354. ><DT
  46355. >LXVIII. <A
  46356. HREF="#ref.misc"
  46357. >Miscellaneous Functions</A
  46358. ></DT
  46359. ><DT
  46360. >LXIX. <A
  46361. HREF="#ref.mnogosearch"
  46362. >mnoGoSearch Functions</A
  46363. ></DT
  46364. ><DT
  46365. >LXX. <A
  46366. HREF="#ref.msql"
  46367. >mSQL Functions</A
  46368. ></DT
  46369. ><DT
  46370. >LXXI. <A
  46371. HREF="#ref.mysql"
  46372. >MySQL Functions</A
  46373. ></DT
  46374. ><DT
  46375. >LXXII. <A
  46376. HREF="#ref.mysqli"
  46377. >Improved MySQL Extension</A
  46378. ></DT
  46379. ><DT
  46380. >LXXIII. <A
  46381. HREF="#ref.msession"
  46382. >Mohawk Software Session Handler Functions</A
  46383. ></DT
  46384. ><DT
  46385. >LXXIV. <A
  46386. HREF="#ref.muscat"
  46387. >muscat Functions</A
  46388. ></DT
  46389. ><DT
  46390. >LXXV. <A
  46391. HREF="#ref.network"
  46392. >Network Functions</A
  46393. ></DT
  46394. ><DT
  46395. >LXXVI. <A
  46396. HREF="#ref.ncurses"
  46397. >Ncurses Terminal Screen Control Functions</A
  46398. ></DT
  46399. ><DT
  46400. >LXXVII. <A
  46401. HREF="#ref.notes"
  46402. >Lotus Notes Functions</A
  46403. ></DT
  46404. ><DT
  46405. >LXXVIII. <A
  46406. HREF="#ref.nsapi"
  46407. >NSAPI-specific Functions</A
  46408. ></DT
  46409. ><DT
  46410. >LXXIX. <A
  46411. HREF="#ref.uodbc"
  46412. >ODBC Functions (Unified)</A
  46413. ></DT
  46414. ><DT
  46415. >LXXX. <A
  46416. HREF="#ref.objaggregation"
  46417. >Object Aggregation/Composition Functions</A
  46418. ></DT
  46419. ><DT
  46420. >LXXXI. <A
  46421. HREF="#ref.oci8"
  46422. >Oracle 8 functions</A
  46423. ></DT
  46424. ><DT
  46425. >LXXXII. <A
  46426. HREF="#ref.openal"
  46427. >OpenAL Audio Bindings</A
  46428. ></DT
  46429. ><DT
  46430. >LXXXIII. <A
  46431. HREF="#ref.openssl"
  46432. >OpenSSL Functions</A
  46433. ></DT
  46434. ><DT
  46435. >LXXXIV. <A
  46436. HREF="#ref.oracle"
  46437. >Oracle Functions</A
  46438. ></DT
  46439. ><DT
  46440. >LXXXV. <A
  46441. HREF="#ref.ovrimos"
  46442. >Ovrimos SQL Functions</A
  46443. ></DT
  46444. ><DT
  46445. >LXXXVI. <A
  46446. HREF="#ref.outcontrol"
  46447. >Output Control Functions</A
  46448. ></DT
  46449. ><DT
  46450. >LXXXVII. <A
  46451. HREF="#ref.overload"
  46452. >Object property and method call overloading</A
  46453. ></DT
  46454. ><DT
  46455. >LXXXVIII. <A
  46456. HREF="#ref.parsekit"
  46457. >Parsekit Functions</A
  46458. ></DT
  46459. ><DT
  46460. >LXXXIX. <A
  46461. HREF="#ref.pdf"
  46462. >PDF functions</A
  46463. ></DT
  46464. ><DT
  46465. >XC. <A
  46466. HREF="#ref.pdo"
  46467. >PDO Functions</A
  46468. ></DT
  46469. ><DT
  46470. >XCI. <A
  46471. HREF="#ref.pfpro"
  46472. >Verisign Payflow Pro Functions</A
  46473. ></DT
  46474. ><DT
  46475. >XCII. <A
  46476. HREF="#ref.info"
  46477. >PHP Options&Information</A
  46478. ></DT
  46479. ><DT
  46480. >XCIII. <A
  46481. HREF="#ref.posix"
  46482. >POSIX Functions</A
  46483. ></DT
  46484. ><DT
  46485. >XCIV. <A
  46486. HREF="#ref.pgsql"
  46487. >PostgreSQL Functions</A
  46488. ></DT
  46489. ><DT
  46490. >XCV. <A
  46491. HREF="#ref.pcntl"
  46492. >Process Control Functions</A
  46493. ></DT
  46494. ><DT
  46495. >XCVI. <A
  46496. HREF="#ref.exec"
  46497. >Program Execution Functions</A
  46498. ></DT
  46499. ><DT
  46500. >XCVII. <A
  46501. HREF="#ref.printer"
  46502. >Printer Functions</A
  46503. ></DT
  46504. ><DT
  46505. >XCVIII. <A
  46506. HREF="#ref.pspell"
  46507. >Pspell Functions</A
  46508. ></DT
  46509. ><DT
  46510. >XCIX. <A
  46511. HREF="#ref.readline"
  46512. >GNU Readline</A
  46513. ></DT
  46514. ><DT
  46515. >C. <A
  46516. HREF="#ref.recode"
  46517. >GNU Recode Functions</A
  46518. ></DT
  46519. ><DT
  46520. >CI. <A
  46521. HREF="#ref.pcre"
  46522. >Regular Expression Functions (Perl-Compatible)</A
  46523. ></DT
  46524. ><DT
  46525. >CII. <A
  46526. HREF="#ref.qtdom"
  46527. >qtdom Functions</A
  46528. ></DT
  46529. ><DT
  46530. >CIII. <A
  46531. HREF="#ref.rar"
  46532. >Rar Functions</A
  46533. ></DT
  46534. ><DT
  46535. >CIV. <A
  46536. HREF="#ref.regex"
  46537. >Regular Expression Functions (POSIX Extended)</A
  46538. ></DT
  46539. ><DT
  46540. >CV. <A
  46541. HREF="#ref.ssh2"
  46542. >Secure Shell2 Functions</A
  46543. ></DT
  46544. ><DT
  46545. >CVI. <A
  46546. HREF="#ref.sem"
  46547. >Semaphore, Shared Memory and IPC Functions</A
  46548. ></DT
  46549. ><DT
  46550. >CVII. <A
  46551. HREF="#ref.sesam"
  46552. >SESAM Database Functions</A
  46553. ></DT
  46554. ><DT
  46555. >CVIII. <A
  46556. HREF="#ref.session"
  46557. >Session Handling Functions</A
  46558. ></DT
  46559. ><DT
  46560. >CIX. <A
  46561. HREF="#ref.shmop"
  46562. >Shared Memory Functions</A
  46563. ></DT
  46564. ><DT
  46565. >CX. <A
  46566. HREF="#ref.simplexml"
  46567. >SimpleXML functions</A
  46568. ></DT
  46569. ><DT
  46570. >CXI. <A
  46571. HREF="#ref.soap"
  46572. >SOAP Functions</A
  46573. ></DT
  46574. ><DT
  46575. >CXII. <A
  46576. HREF="#ref.sqlite"
  46577. >SQLite</A
  46578. ></DT
  46579. ><DT
  46580. >CXIII. <A
  46581. HREF="#ref.swf"
  46582. >Shockwave Flash Functions</A
  46583. ></DT
  46584. ><DT
  46585. >CXIV. <A
  46586. HREF="#ref.snmp"
  46587. >SNMP Functions</A
  46588. ></DT
  46589. ><DT
  46590. >CXV. <A
  46591. HREF="#ref.sockets"
  46592. >Socket Functions</A
  46593. ></DT
  46594. ><DT
  46595. >CXVI. <A
  46596. HREF="#ref.spl"
  46597. >Standard PHP Library (SPL) Functions</A
  46598. ></DT
  46599. ><DT
  46600. >CXVII. <A
  46601. HREF="#ref.stream"
  46602. >Stream Functions</A
  46603. ></DT
  46604. ><DT
  46605. >CXVIII. <A
  46606. HREF="#ref.strings"
  46607. >String Functions</A
  46608. ></DT
  46609. ><DT
  46610. >CXIX. <A
  46611. HREF="#ref.sybase"
  46612. >Sybase Functions</A
  46613. ></DT
  46614. ><DT
  46615. >CXX. <A
  46616. HREF="#ref.tcpwrap"
  46617. >TCP Wrappers Functions</A
  46618. ></DT
  46619. ><DT
  46620. >CXXI. <A
  46621. HREF="#ref.tidy"
  46622. >Tidy Functions</A
  46623. ></DT
  46624. ><DT
  46625. >CXXII. <A
  46626. HREF="#ref.tokenizer"
  46627. >Tokenizer Functions</A
  46628. ></DT
  46629. ><DT
  46630. >CXXIII. <A
  46631. HREF="#ref.url"
  46632. >URL Functions</A
  46633. ></DT
  46634. ><DT
  46635. >CXXIV. <A
  46636. HREF="#ref.var"
  46637. >Variable Functions</A
  46638. ></DT
  46639. ><DT
  46640. >CXXV. <A
  46641. HREF="#ref.vpopmail"
  46642. >vpopmail Functions</A
  46643. ></DT
  46644. ><DT
  46645. >CXXVI. <A
  46646. HREF="#ref.w32api"
  46647. >W32api Functions</A
  46648. ></DT
  46649. ><DT
  46650. >CXXVII. <A
  46651. HREF="#ref.wddx"
  46652. >WDDX Functions</A
  46653. ></DT
  46654. ><DT
  46655. >CXXVIII. <A
  46656. HREF="#ref.xattr"
  46657. >xattr Functions</A
  46658. ></DT
  46659. ><DT
  46660. >CXXIX. <A
  46661. HREF="#ref.xml"
  46662. >XML Parser Functions</A
  46663. ></DT
  46664. ><DT
  46665. >CXXX. <A
  46666. HREF="#ref.xmlrpc"
  46667. >XML-RPC Functions</A
  46668. ></DT
  46669. ><DT
  46670. >CXXXI. <A
  46671. HREF="#ref.xdiff"
  46672. >xdiff Functions</A
  46673. ></DT
  46674. ><DT
  46675. >CXXXII. <A
  46676. HREF="#ref.xsl"
  46677. >XSL functions</A
  46678. ></DT
  46679. ><DT
  46680. >CXXXIII. <A
  46681. HREF="#ref.xslt"
  46682. >XSLT Functions</A
  46683. ></DT
  46684. ><DT
  46685. >CXXXIV. <A
  46686. HREF="#ref.yaz"
  46687. >YAZ Functions</A
  46688. ></DT
  46689. ><DT
  46690. >CXXXV. <A
  46691. HREF="#ref.nis"
  46692. >YP/NIS Functions</A
  46693. ></DT
  46694. ><DT
  46695. >CXXXVI. <A
  46696. HREF="#ref.zip"
  46697. >Zip File Functions (Read Only Access)</A
  46698. ></DT
  46699. ><DT
  46700. >CXXXVII. <A
  46701. HREF="#ref.zlib"
  46702. >Zlib Compression Functions</A
  46703. ></DT
  46704. ></DL
  46705. ></DIV
  46706. ></DIV
  46707. ><DIV
  46708. CLASS="reference"
  46709. ><A
  46710. NAME="ref.apache"
  46711. ></A
  46712. ><DIV
  46713. CLASS="TITLEPAGE"
  46714. ><H1
  46715. CLASS="title"
  46716. >I. Apache-specific Functions</H1
  46717. ><DIV
  46718. CLASS="PARTINTRO"
  46719. ><A
  46720. NAME="AEN7742"
  46721. ></A
  46722. ><DIV
  46723. CLASS="section"
  46724. ><H2
  46725. CLASS="section"
  46726. ><A
  46727. NAME="apache.intro"
  46728. >Introduction</A
  46729. ></H2
  46730. ><P
  46731. >      These functions are only available when running PHP as an Apache module.
  46732.     </P
  46733. ><DIV
  46734. CLASS="note"
  46735. ><BLOCKQUOTE
  46736. CLASS="note"
  46737. ><P
  46738. ><B
  46739. >Note: </B
  46740. >
  46741.       As of PHP 4.3.2, <VAR
  46742. CLASS="envar"
  46743. >PATH_TRANSLATED</VAR
  46744. > is no longer set 
  46745.       implicitly under the Apache 2 <ACRONYM
  46746. CLASS="acronym"
  46747. >SAPI</ACRONYM
  46748. > in contrast 
  46749.       to the situation in Apache 1, where it's set to the same value as 
  46750.       the <VAR
  46751. CLASS="envar"
  46752. >SCRIPT_FILENAME</VAR
  46753. > server variable when it's not 
  46754.       populated by Apache.  This change was made to comply with the 
  46755.       <ACRONYM
  46756. CLASS="acronym"
  46757. >CGI</ACRONYM
  46758. > specification that 
  46759.       <VAR
  46760. CLASS="envar"
  46761. >PATH_TRANSLATED</VAR
  46762. > should only exist if 
  46763.       <VAR
  46764. CLASS="envar"
  46765. >PATH_INFO</VAR
  46766. > is defined.
  46767.      </P
  46768. ><P
  46769. >       Apache 2 users may use <VAR
  46770. CLASS="literal"
  46771. >AcceptPathInfo = On</VAR
  46772. > inside
  46773.       <TT
  46774. CLASS="filename"
  46775. >httpd.conf</TT
  46776. > to define <VAR
  46777. CLASS="envar"
  46778. >PATH_INFO</VAR
  46779. >.
  46780.      </P
  46781. ></BLOCKQUOTE
  46782. ></DIV
  46783. ></DIV
  46784. ><DIV
  46785. CLASS="section"
  46786. ><HR><H2
  46787. CLASS="section"
  46788. ><A
  46789. NAME="apache.installation"
  46790. >Installation</A
  46791. ></H2
  46792. ><P
  46793. >      For PHP installation on Apache see the <A
  46794. HREF="#install"
  46795. >installation chapter</A
  46796. >.
  46797.     </P
  46798. ></DIV
  46799. ><DIV
  46800. CLASS="section"
  46801. ><HR><H2
  46802. CLASS="section"
  46803. ><A
  46804. NAME="apache.configuration"
  46805. >Runtime Configuration</A
  46806. ></H2
  46807. ><P
  46808. >   The behaviour of the Apache PHP module is affected by settings in <TT
  46809. CLASS="filename"
  46810. >php.ini</TT
  46811. >.
  46812.   Configuration settings from <TT
  46813. CLASS="filename"
  46814. >php.ini</TT
  46815. > may be overridden by
  46816.   <A
  46817. HREF="#configuration.changes.apache"
  46818. >php_flag</A
  46819. > settings
  46820.   in the server configuration file or local <TT
  46821. CLASS="filename"
  46822. >.htaccess</TT
  46823. > files.
  46824.  </P
  46825. ><TABLE
  46826. WIDTH="100%"
  46827. BORDER="0"
  46828. CELLPADDING="0"
  46829. CELLSPACING="0"
  46830. CLASS="EXAMPLE"
  46831. ><TR
  46832. ><TD
  46833. ><DIV
  46834. CLASS="example"
  46835. ><A
  46836. NAME="AEN7769"
  46837. ></A
  46838. ><P
  46839. ><B
  46840. >Example 1. Turning off PHP parsing for a directory using <TT
  46841. CLASS="filename"
  46842. >.htaccess</TT
  46843. ></B
  46844. ></P
  46845. ><TABLE
  46846. BORDER="0"
  46847. BGCOLOR="#E0E0E0"
  46848. CELLPADDING="5"
  46849. ><TR
  46850. ><TD
  46851. ><PRE
  46852. CLASS="programlisting"
  46853. >php_flag engine off</PRE
  46854. ></TD
  46855. ></TR
  46856. ></TABLE
  46857. ></DIV
  46858. ></TD
  46859. ></TR
  46860. ></TABLE
  46861. ><P
  46862. >   <DIV
  46863. CLASS="table"
  46864. ><A
  46865. NAME="AEN7774"
  46866. ></A
  46867. ><P
  46868. ><B
  46869. >Table 1. Apache configuration options</B
  46870. ></P
  46871. ><TABLE
  46872. BORDER="1"
  46873. CLASS="CALSTABLE"
  46874. ><COL><COL><COL><THEAD
  46875. ><TR
  46876. ><TH
  46877. >Name</TH
  46878. ><TH
  46879. >Default</TH
  46880. ><TH
  46881. >Changeable</TH
  46882. ></TR
  46883. ></THEAD
  46884. ><TBODY
  46885. ><TR
  46886. ><TD
  46887. >engine</TD
  46888. ><TD
  46889. >On</TD
  46890. ><TD
  46891. >PHP_INI_ALL</TD
  46892. ></TR
  46893. ><TR
  46894. ><TD
  46895. >child_terminate</TD
  46896. ><TD
  46897. >Off</TD
  46898. ><TD
  46899. >PHP_INI_ALL</TD
  46900. ></TR
  46901. ><TR
  46902. ><TD
  46903. >last_modified</TD
  46904. ><TD
  46905. >Off</TD
  46906. ><TD
  46907. >PHP_INI_ALL</TD
  46908. ></TR
  46909. ><TR
  46910. ><TD
  46911. >xbithack</TD
  46912. ><TD
  46913. >Off</TD
  46914. ><TD
  46915. >PHP_INI_ALL</TD
  46916. ></TR
  46917. ></TBODY
  46918. ></TABLE
  46919. ></DIV
  46920. >
  46921.   For further details and definition of the PHP_INI_* constants see
  46922.   <A
  46923. HREF="#function.ini-set"
  46924. ><B
  46925. CLASS="function"
  46926. >ini_set()</B
  46927. ></A
  46928. >.
  46929.  </P
  46930. ><P
  46931. >Here's a short explanation of
  46932. the configuration directives.</P
  46933. ><P
  46934. >   <P
  46935. ></P
  46936. ><DIV
  46937. CLASS="variablelist"
  46938. ><DL
  46939. ><DT
  46940. ><A
  46941. NAME="ini.engine"
  46942. ></A
  46943. ><VAR
  46944. CLASS="parameter"
  46945. >engine</VAR
  46946. >
  46947.      <A
  46948. HREF="#language.types.boolean"
  46949. ><B
  46950. CLASS="type"
  46951. >boolean</B
  46952. ></A
  46953. ></DT
  46954. ><DD
  46955. ><P
  46956. >       Turns PHP parsing on or off.
  46957.       This directive is really only useful in the Apache module
  46958.       version of PHP. It is used by sites that would like to turn
  46959.       PHP parsing on and off on a per-directory or per-virtual
  46960.       server basis. By putting <KBD
  46961. CLASS="userinput"
  46962. >engine off</KBD
  46963. >
  46964.       in the appropriate places in the <TT
  46965. CLASS="filename"
  46966. >httpd.conf</TT
  46967. > file, PHP can
  46968.       be enabled or disabled.
  46969.      </P
  46970. ></DD
  46971. ><DT
  46972. ><A
  46973. NAME="ini.child-terminate"
  46974. ></A
  46975. ><VAR
  46976. CLASS="parameter"
  46977. >child_terminate</VAR
  46978. >
  46979.      <A
  46980. HREF="#language.types.boolean"
  46981. ><B
  46982. CLASS="type"
  46983. >boolean</B
  46984. ></A
  46985. ></DT
  46986. ><DD
  46987. ><P
  46988. >       Specify whether PHP scripts may request child process termination on end of request, 
  46989.       see also <A
  46990. HREF="#function.apache-child-terminate"
  46991. ><B
  46992. CLASS="function"
  46993. >apache_child_terminate()</B
  46994. ></A
  46995. >.
  46996.      </P
  46997. ></DD
  46998. ><DT
  46999. ><A
  47000. NAME="ini.last-modified"
  47001. ></A
  47002. ><VAR
  47003. CLASS="parameter"
  47004. >last_modified</VAR
  47005. >
  47006.      <A
  47007. HREF="#language.types.boolean"
  47008. ><B
  47009. CLASS="type"
  47010. >boolean</B
  47011. ></A
  47012. ></DT
  47013. ><DD
  47014. ><P
  47015. >       Send PHP scripts modification date as Last-Modified: header for this request.
  47016.      </P
  47017. ></DD
  47018. ><DT
  47019. ><A
  47020. NAME="ini.xbithack"
  47021. ></A
  47022. ><VAR
  47023. CLASS="parameter"
  47024. >xbithack</VAR
  47025. >
  47026.      <A
  47027. HREF="#language.types.boolean"
  47028. ><B
  47029. CLASS="type"
  47030. >boolean</B
  47031. ></A
  47032. ></DT
  47033. ><DD
  47034. ><P
  47035. >       Parse files with executable bit set as PHP regardless of their file ending.
  47036.      </P
  47037. ></DD
  47038. ></DL
  47039. ></DIV
  47040. >
  47041.  </P
  47042. ></DIV
  47043. ><DIV
  47044. CLASS="section"
  47045. ><HR><H2
  47046. CLASS="section"
  47047. ><A
  47048. NAME="apache.resources"
  47049. >Resource Types</A
  47050. ></H2
  47051. ><P
  47052. >This extension has no resource types defined.</P
  47053. ></DIV
  47054. ><DIV
  47055. CLASS="section"
  47056. ><HR><H2
  47057. CLASS="section"
  47058. ><A
  47059. NAME="apache.constants"
  47060. >Predefined Constants</A
  47061. ></H2
  47062. ><P
  47063. >This extension has no constants defined.</P
  47064. ></DIV
  47065. ></DIV
  47066. ><DIV
  47067. CLASS="TOC"
  47068. ><DL
  47069. ><DT
  47070. ><B
  47071. >Table of Contents</B
  47072. ></DT
  47073. ><DT
  47074. ><A
  47075. HREF="#function.apache-child-terminate"
  47076. >apache_child_terminate</A
  47077. > -- Terminate apache process after this request</DT
  47078. ><DT
  47079. ><A
  47080. HREF="#function.apache-get-modules"
  47081. >apache_get_modules</A
  47082. > -- 
  47083.      Get a list of loaded Apache modules
  47084.     </DT
  47085. ><DT
  47086. ><A
  47087. HREF="#function.apache-get-version"
  47088. >apache_get_version</A
  47089. > -- 
  47090.      Fetch Apache version
  47091.     </DT
  47092. ><DT
  47093. ><A
  47094. HREF="#function.apache-getenv"
  47095. >apache_getenv</A
  47096. > -- Get an Apache subprocess_env variable</DT
  47097. ><DT
  47098. ><A
  47099. HREF="#function.apache-lookup-uri"
  47100. >apache_lookup_uri</A
  47101. > -- 
  47102.      Perform a partial request for the specified URI and return all
  47103.      info about it
  47104.     </DT
  47105. ><DT
  47106. ><A
  47107. HREF="#function.apache-note"
  47108. >apache_note</A
  47109. > -- Get and set apache request notes</DT
  47110. ><DT
  47111. ><A
  47112. HREF="#function.apache-request-headers"
  47113. >apache_request_headers</A
  47114. > -- Fetch all HTTP request headers</DT
  47115. ><DT
  47116. ><A
  47117. HREF="#function.apache-reset-timeout"
  47118. >apache_reset_timeout</A
  47119. > -- 
  47120.      Reset the Apache write timer
  47121.     </DT
  47122. ><DT
  47123. ><A
  47124. HREF="#function.apache-response-headers"
  47125. >apache_response_headers</A
  47126. > -- 
  47127.      Fetch all HTTP response headers
  47128.     </DT
  47129. ><DT
  47130. ><A
  47131. HREF="#function.apache-setenv"
  47132. >apache_setenv</A
  47133. > -- Set an Apache subprocess_env variable</DT
  47134. ><DT
  47135. ><A
  47136. HREF="#function.ascii2ebcdic"
  47137. >ascii2ebcdic</A
  47138. > -- Translate string from ASCII to EBCDIC</DT
  47139. ><DT
  47140. ><A
  47141. HREF="#function.ebcdic2ascii"
  47142. >ebcdic2ascii</A
  47143. > -- Translate string from EBCDIC to ASCII</DT
  47144. ><DT
  47145. ><A
  47146. HREF="#function.getallheaders"
  47147. >getallheaders</A
  47148. > -- Fetch all HTTP request headers</DT
  47149. ><DT
  47150. ><A
  47151. HREF="#function.virtual"
  47152. >virtual</A
  47153. > -- Perform an Apache sub-request</DT
  47154. ></DL
  47155. ></DIV
  47156. ></DIV
  47157. ><H1
  47158. ><A
  47159. NAME="function.apache-child-terminate"
  47160. ></A
  47161. >apache_child_terminate</H1
  47162. ><DIV
  47163. CLASS="refnamediv"
  47164. ><A
  47165. NAME="AEN7837"
  47166. ></A
  47167. ><P
  47168. >    (PHP 4 >= 4.0.5, PHP 5)</P
  47169. >apache_child_terminate -- Terminate apache process after this request</DIV
  47170. ><DIV
  47171. CLASS="refsect1"
  47172. ><A
  47173. NAME="AEN7840"
  47174. ></A
  47175. ><H2
  47176. >Description</H2
  47177. >bool <B
  47178. CLASS="methodname"
  47179. >apache_child_terminate</B
  47180. > ( void )<BR
  47181. ></BR
  47182. ><P
  47183. >      <B
  47184. CLASS="function"
  47185. >apache_child_terminate()</B
  47186. > will register the
  47187.      Apache process executing the current PHP request for termination
  47188.      once execution of PHP code it is completed. It may be used to
  47189.      terminate a process after a script with high memory consumption has
  47190.      been run as memory will usually only be freed internally but not
  47191.      given back to the operating system. 
  47192.     </P
  47193. ><DIV
  47194. CLASS="note"
  47195. ><BLOCKQUOTE
  47196. CLASS="note"
  47197. ><P
  47198. ><B
  47199. >Note: </B
  47200. >
  47201.       The availability of this feature is controlled by the <TT
  47202. CLASS="filename"
  47203. >php.ini</TT
  47204. > directive
  47205.       <VAR
  47206. CLASS="option"
  47207. >child_terminate</VAR
  47208. >, which is set to <VAR
  47209. CLASS="literal"
  47210. >off</VAR
  47211. >
  47212.       by default.
  47213.      </P
  47214. ><P
  47215. >       This feature is also not available on multithreaded versions of apache 
  47216.       like the win32 version.
  47217.      </P
  47218. ></BLOCKQUOTE
  47219. ></DIV
  47220. ><P
  47221. >      See also <A
  47222. HREF="#function.exit"
  47223. ><B
  47224. CLASS="function"
  47225. >exit()</B
  47226. ></A
  47227. >.
  47228.     </P
  47229. ></DIV
  47230. ><H1
  47231. ><A
  47232. NAME="function.apache-get-modules"
  47233. ></A
  47234. >apache_get_modules</H1
  47235. ><DIV
  47236. CLASS="refnamediv"
  47237. ><A
  47238. NAME="AEN7857"
  47239. ></A
  47240. ><P
  47241. >    (PHP 4 >= 4.3.2, PHP 5)</P
  47242. >apache_get_modules -- 
  47243.      Get a list of loaded Apache modules
  47244.     </DIV
  47245. ><DIV
  47246. CLASS="refsect1"
  47247. ><A
  47248. NAME="AEN7860"
  47249. ></A
  47250. ><H2
  47251. >Description</H2
  47252. >array <B
  47253. CLASS="methodname"
  47254. >apache_get_modules</B
  47255. > ( void )<BR
  47256. ></BR
  47257. ><P
  47258. >      This function returns an array with the loaded Apache modules.
  47259.     </P
  47260. ><P
  47261. >      <TABLE
  47262. WIDTH="100%"
  47263. BORDER="0"
  47264. CELLPADDING="0"
  47265. CELLSPACING="0"
  47266. CLASS="EXAMPLE"
  47267. ><TR
  47268. ><TD
  47269. ><DIV
  47270. CLASS="example"
  47271. ><A
  47272. NAME="AEN7868"
  47273. ></A
  47274. ><P
  47275. ><B
  47276. >Example 1. <B
  47277. CLASS="function"
  47278. >apache_get_modules()</B
  47279. > example</B
  47280. ></P
  47281. ><TABLE
  47282. BORDER="0"
  47283. BGCOLOR="#E0E0E0"
  47284. CELLPADDING="5"
  47285. ><TR
  47286. ><TD
  47287. ><PRE
  47288. CLASS="php"
  47289. ><?php
  47290. print_r(apache_get_modules());
  47291. ?></PRE
  47292. ></TD
  47293. ></TR
  47294. ></TABLE
  47295. ><P
  47296. >The above example will output 
  47297. something similar to:</P
  47298. ><TABLE
  47299. BORDER="0"
  47300. BGCOLOR="#E0E0E0"
  47301. CELLPADDING="5"
  47302. ><TR
  47303. ><TD
  47304. ><PRE
  47305. CLASS="screen"
  47306. >Array
  47307. (
  47308.     [0] => core
  47309.     [1] => http_core
  47310.     [2] => mod_so
  47311.     [3] => sapi_apache2
  47312.     [4] => mod_mime
  47313.     [5] => mod_rewrite
  47314. )</PRE
  47315. ></TD
  47316. ></TR
  47317. ></TABLE
  47318. ></DIV
  47319. ></TD
  47320. ></TR
  47321. ></TABLE
  47322. >
  47323.     </P
  47324. ><DIV
  47325. CLASS="note"
  47326. ><BLOCKQUOTE
  47327. CLASS="note"
  47328. ><P
  47329. ><B
  47330. >Note: </B
  47331. >
  47332.       This function is available only in Apache 2 <SPAN
  47333. CLASS="emphasis"
  47334. ><I
  47335. CLASS="emphasis"
  47336. >handler</I
  47337. ></SPAN
  47338. >.
  47339.       As of PHP 5, it is available also in Apache 2 <SPAN
  47340. CLASS="emphasis"
  47341. ><I
  47342. CLASS="emphasis"
  47343. >filter</I
  47344. ></SPAN
  47345. >
  47346.       and Apache 1.
  47347.      </P
  47348. ></BLOCKQUOTE
  47349. ></DIV
  47350. ></DIV
  47351. ><H1
  47352. ><A
  47353. NAME="function.apache-get-version"
  47354. ></A
  47355. >apache_get_version</H1
  47356. ><DIV
  47357. CLASS="refnamediv"
  47358. ><A
  47359. NAME="AEN7879"
  47360. ></A
  47361. ><P
  47362. >    (PHP 4 >= 4.3.2, PHP 5)</P
  47363. >apache_get_version -- 
  47364.      Fetch Apache version
  47365.     </DIV
  47366. ><DIV
  47367. CLASS="refsect1"
  47368. ><A
  47369. NAME="AEN7882"
  47370. ></A
  47371. ><H2
  47372. >Description</H2
  47373. >string <B
  47374. CLASS="methodname"
  47375. >apache_get_version</B
  47376. > ( void )<BR
  47377. ></BR
  47378. ><P
  47379. >      <B
  47380. CLASS="function"
  47381. >apache_get_version()</B
  47382. > returns the version of Apache as
  47383.      string, or <TT
  47384. CLASS="constant"
  47385. ><B
  47386. >FALSE</B
  47387. ></TT
  47388. > on failure.
  47389.     </P
  47390. ><TABLE
  47391. WIDTH="100%"
  47392. BORDER="0"
  47393. CELLPADDING="0"
  47394. CELLSPACING="0"
  47395. CLASS="EXAMPLE"
  47396. ><TR
  47397. ><TD
  47398. ><DIV
  47399. CLASS="example"
  47400. ><A
  47401. NAME="AEN7891"
  47402. ></A
  47403. ><P
  47404. ><B
  47405. >Example 1. <B
  47406. CLASS="function"
  47407. >apache_get_version()</B
  47408. > example</B
  47409. ></P
  47410. ><TABLE
  47411. BORDER="0"
  47412. BGCOLOR="#E0E0E0"
  47413. CELLPADDING="5"
  47414. ><TR
  47415. ><TD
  47416. ><PRE
  47417. CLASS="php"
  47418. ><?php
  47419. $version = apache_get_version();
  47420. echo "$version\n";
  47421. ?></PRE
  47422. ></TD
  47423. ></TR
  47424. ></TABLE
  47425. ><P
  47426. >The above example will output 
  47427. something similar to:</P
  47428. ><TABLE
  47429. BORDER="0"
  47430. BGCOLOR="#E0E0E0"
  47431. CELLPADDING="5"
  47432. ><TR
  47433. ><TD
  47434. ><PRE
  47435. CLASS="screen"
  47436. >Apache/1.3.29 (Unix) PHP/4.3.4</PRE
  47437. ></TD
  47438. ></TR
  47439. ></TABLE
  47440. ></DIV
  47441. ></TD
  47442. ></TR
  47443. ></TABLE
  47444. ><DIV
  47445. CLASS="note"
  47446. ><BLOCKQUOTE
  47447. CLASS="note"
  47448. ><P
  47449. ><B
  47450. >Note: </B
  47451. >
  47452.       This function is available only in Apache 2 <SPAN
  47453. CLASS="emphasis"
  47454. ><I
  47455. CLASS="emphasis"
  47456. >handler</I
  47457. ></SPAN
  47458. >.
  47459.       As of PHP 4.3.4, it is available also in Apache 1 and as of PHP 5, it is
  47460.       available also in Apache 2 <SPAN
  47461. CLASS="emphasis"
  47462. ><I
  47463. CLASS="emphasis"
  47464. >filter</I
  47465. ></SPAN
  47466. >.
  47467.      </P
  47468. ></BLOCKQUOTE
  47469. ></DIV
  47470. ><P
  47471. >      See also <A
  47472. HREF="#function.phpinfo"
  47473. ><B
  47474. CLASS="function"
  47475. >phpinfo()</B
  47476. ></A
  47477. >.
  47478.     </P
  47479. ></DIV
  47480. ><H1
  47481. ><A
  47482. NAME="function.apache-getenv"
  47483. ></A
  47484. >apache_getenv</H1
  47485. ><DIV
  47486. CLASS="refnamediv"
  47487. ><A
  47488. NAME="AEN7904"
  47489. ></A
  47490. ><P
  47491. >    (PHP 4 >= 4.3.0, PHP 5)</P
  47492. >apache_getenv -- Get an Apache subprocess_env variable</DIV
  47493. ><DIV
  47494. CLASS="refsect1"
  47495. ><A
  47496. NAME="AEN7907"
  47497. ></A
  47498. ><H2
  47499. >Description</H2
  47500. >string <B
  47501. CLASS="methodname"
  47502. >apache_getenv</B
  47503. > ( string variable [, bool walk_to_top])<BR
  47504. ></BR
  47505. ><P
  47506. >      <B
  47507. CLASS="function"
  47508. >apache_getenv()</B
  47509. > returns the value of the Apache
  47510.      environment variable specified by <VAR
  47511. CLASS="parameter"
  47512. >variable</VAR
  47513. >, or
  47514.      <TT
  47515. CLASS="constant"
  47516. ><B
  47517. >FALSE</B
  47518. ></TT
  47519. > on failure.
  47520.     </P
  47521. ><TABLE
  47522. WIDTH="100%"
  47523. BORDER="0"
  47524. CELLPADDING="0"
  47525. CELLSPACING="0"
  47526. CLASS="EXAMPLE"
  47527. ><TR
  47528. ><TD
  47529. ><DIV
  47530. CLASS="example"
  47531. ><A
  47532. NAME="AEN7922"
  47533. ></A
  47534. ><P
  47535. ><B
  47536. >Example 1. <B
  47537. CLASS="function"
  47538. >apache_getenv()</B
  47539. > example</B
  47540. ></P
  47541. ><TABLE
  47542. BORDER="0"
  47543. BGCOLOR="#E0E0E0"
  47544. CELLPADDING="5"
  47545. ><TR
  47546. ><TD
  47547. ><PRE
  47548. CLASS="php"
  47549. ><?php
  47550. $ret = apache_getenv("SERVER_ADDR");
  47551. echo $ret;
  47552. ?></PRE
  47553. ></TD
  47554. ></TR
  47555. ></TABLE
  47556. ><P
  47557. >       The example above shows how to retrieve the value of the Apache
  47558.       environment variable "SERVER_ADDR".
  47559.      </P
  47560. ></DIV
  47561. ></TD
  47562. ></TR
  47563. ></TABLE
  47564. ><P
  47565. >      See also <A
  47566. HREF="#function.apache-setenv"
  47567. ><B
  47568. CLASS="function"
  47569. >apache_setenv()</B
  47570. ></A
  47571. >.
  47572.     </P
  47573. ></DIV
  47574. ><H1
  47575. ><A
  47576. NAME="function.apache-lookup-uri"
  47577. ></A
  47578. >apache_lookup_uri</H1
  47579. ><DIV
  47580. CLASS="refnamediv"
  47581. ><A
  47582. NAME="AEN7930"
  47583. ></A
  47584. ><P
  47585. >    (PHP 3>= 3.0.4, PHP 4 , PHP 5)</P
  47586. >apache_lookup_uri -- 
  47587.      Perform a partial request for the specified URI and return all
  47588.      info about it
  47589.     </DIV
  47590. ><DIV
  47591. CLASS="refsect1"
  47592. ><A
  47593. NAME="AEN7933"
  47594. ></A
  47595. ><H2
  47596. >Description</H2
  47597. >object <B
  47598. CLASS="methodname"
  47599. >apache_lookup_uri</B
  47600. > ( string filename)<BR
  47601. ></BR
  47602. ><P
  47603. >      This performs a partial request for a URI.  It goes just far
  47604.      enough to obtain all the important information about the given
  47605.      resource and returns this information in a class.  The properties
  47606.      of the returned class are:
  47607.      <P
  47608. ></P
  47609. ><TABLE
  47610. BORDER="0"
  47611. ><TBODY
  47612. ><TR
  47613. ><TD
  47614. >status</TD
  47615. ></TR
  47616. ><TR
  47617. ><TD
  47618. >the_request</TD
  47619. ></TR
  47620. ><TR
  47621. ><TD
  47622. >status_line</TD
  47623. ></TR
  47624. ><TR
  47625. ><TD
  47626. >method</TD
  47627. ></TR
  47628. ><TR
  47629. ><TD
  47630. >content_type</TD
  47631. ></TR
  47632. ><TR
  47633. ><TD
  47634. >handler</TD
  47635. ></TR
  47636. ><TR
  47637. ><TD
  47638. >uri</TD
  47639. ></TR
  47640. ><TR
  47641. ><TD
  47642. >filename</TD
  47643. ></TR
  47644. ><TR
  47645. ><TD
  47646. >path_info</TD
  47647. ></TR
  47648. ><TR
  47649. ><TD
  47650. >args</TD
  47651. ></TR
  47652. ><TR
  47653. ><TD
  47654. >boundary</TD
  47655. ></TR
  47656. ><TR
  47657. ><TD
  47658. >no_cache</TD
  47659. ></TR
  47660. ><TR
  47661. ><TD
  47662. >no_local_copy</TD
  47663. ></TR
  47664. ><TR
  47665. ><TD
  47666. >allowed</TD
  47667. ></TR
  47668. ><TR
  47669. ><TD
  47670. >send_bodyct</TD
  47671. ></TR
  47672. ><TR
  47673. ><TD
  47674. >bytes_sent</TD
  47675. ></TR
  47676. ><TR
  47677. ><TD
  47678. >byterange</TD
  47679. ></TR
  47680. ><TR
  47681. ><TD
  47682. >clength</TD
  47683. ></TR
  47684. ><TR
  47685. ><TD
  47686. >unparsed_uri</TD
  47687. ></TR
  47688. ><TR
  47689. ><TD
  47690. >mtime</TD
  47691. ></TR
  47692. ><TR
  47693. ><TD
  47694. >request_time</TD
  47695. ></TR
  47696. ></TBODY
  47697. ></TABLE
  47698. ><P
  47699. ></P
  47700. >
  47701.     </P
  47702. ><P
  47703. >      <TABLE
  47704. WIDTH="100%"
  47705. BORDER="0"
  47706. CELLPADDING="0"
  47707. CELLSPACING="0"
  47708. CLASS="EXAMPLE"
  47709. ><TR
  47710. ><TD
  47711. ><DIV
  47712. CLASS="example"
  47713. ><A
  47714. NAME="AEN7965"
  47715. ></A
  47716. ><P
  47717. ><B
  47718. >Example 1. <B
  47719. CLASS="function"
  47720. >apache_lookup_uri()</B
  47721. > example</B
  47722. ></P
  47723. ><TABLE
  47724. BORDER="0"
  47725. BGCOLOR="#E0E0E0"
  47726. CELLPADDING="5"
  47727. ><TR
  47728. ><TD
  47729. ><PRE
  47730. CLASS="php"
  47731. ><?php
  47732. $info = apache_lookup_uri('index.php?var=value');
  47733. print_r($info);
  47734.  
  47735. if (file_exists($info->filename)) {
  47736.     echo 'file exists!';
  47737. }
  47738. ?></PRE
  47739. ></TD
  47740. ></TR
  47741. ></TABLE
  47742. ><P
  47743. >The above example will output 
  47744. something similar to:</P
  47745. ><TABLE
  47746. BORDER="0"
  47747. BGCOLOR="#E0E0E0"
  47748. CELLPADDING="5"
  47749. ><TR
  47750. ><TD
  47751. ><PRE
  47752. CLASS="screen"
  47753. >stdClass Object
  47754. (
  47755.     [status] => 200
  47756.     [the_request] => GET /dir/file.php HTTP/1.1
  47757.     [method] => GET
  47758.     [mtime] => 0
  47759.     [clength] => 0
  47760.     [chunked] => 0
  47761.     [content_type] => application/x-httpd-php
  47762.     [no_cache] => 0
  47763.     [no_local_copy] => 1
  47764.     [unparsed_uri] => /dir/index.php?var=value
  47765.     [uri] => /dir/index.php
  47766.     [filename] => /home/htdocs/dir/index.php
  47767.     [args] => var=value
  47768.     [allowed] => 0
  47769.     [sent_bodyct] => 0
  47770.     [bytes_sent] => 0
  47771.     [request_time] => 1074282764
  47772. )
  47773. file exists!</PRE
  47774. ></TD
  47775. ></TR
  47776. ></TABLE
  47777. ></DIV
  47778. ></TD
  47779. ></TR
  47780. ></TABLE
  47781. >
  47782.     </P
  47783. ><DIV
  47784. CLASS="note"
  47785. ><BLOCKQUOTE
  47786. CLASS="note"
  47787. ><P
  47788. ><B
  47789. >Note: </B
  47790. >
  47791.       <B
  47792. CLASS="function"
  47793. >apache_lookup_uri()</B
  47794. > only works when PHP
  47795.       is installed as an Apache module.
  47796.      </P
  47797. ></BLOCKQUOTE
  47798. ></DIV
  47799. ></DIV
  47800. ><H1
  47801. ><A
  47802. NAME="function.apache-note"
  47803. ></A
  47804. >apache_note</H1
  47805. ><DIV
  47806. CLASS="refnamediv"
  47807. ><A
  47808. NAME="AEN7975"
  47809. ></A
  47810. ><P
  47811. >    (PHP 3>= 3.0.2, PHP 4 , PHP 5)</P
  47812. >apache_note -- Get and set apache request notes</DIV
  47813. ><DIV
  47814. CLASS="refsect1"
  47815. ><A
  47816. NAME="AEN7978"
  47817. ></A
  47818. ><H2
  47819. >Description</H2
  47820. >string <B
  47821. CLASS="methodname"
  47822. >apache_note</B
  47823. > ( string note_name [, string note_value])<BR
  47824. ></BR
  47825. ><P
  47826. >      <B
  47827. CLASS="function"
  47828. >apache_note()</B
  47829. > is an Apache-specific function
  47830.      which gets and sets values in a request's
  47831.      <VAR
  47832. CLASS="literal"
  47833. >notes</VAR
  47834. > table. If called with one argument, it
  47835.      returns the current value of note
  47836.      <VAR
  47837. CLASS="literal"
  47838. >note_name</VAR
  47839. >. If called with two arguments, it
  47840.      sets the value of note <VAR
  47841. CLASS="literal"
  47842. >note_name</VAR
  47843. > to
  47844.      <VAR
  47845. CLASS="literal"
  47846. >note_value</VAR
  47847. > and returns the previous value of
  47848.      note <VAR
  47849. CLASS="literal"
  47850. >note_name</VAR
  47851. >.
  47852.     </P
  47853. ></DIV
  47854. ><H1
  47855. ><A
  47856. NAME="function.apache-request-headers"
  47857. ></A
  47858. >apache_request_headers</H1
  47859. ><DIV
  47860. CLASS="refnamediv"
  47861. ><A
  47862. NAME="AEN7997"
  47863. ></A
  47864. ><P
  47865. >    (PHP 4 >= 4.3.0, PHP 5)</P
  47866. >apache_request_headers -- Fetch all HTTP request headers</DIV
  47867. ><DIV
  47868. CLASS="refsect1"
  47869. ><A
  47870. NAME="AEN8000"
  47871. ></A
  47872. ><H2
  47873. >Description</H2
  47874. >array <B
  47875. CLASS="methodname"
  47876. >apache_request_headers</B
  47877. > ( void )<BR
  47878. ></BR
  47879. ><P
  47880. >      <B
  47881. CLASS="function"
  47882. >apache_request_headers()</B
  47883. > returns an associative
  47884.      array of all the HTTP headers in the current request.  This is only
  47885.      supported when PHP runs as an <SPAN
  47886. CLASS="productname"
  47887. >Apache</SPAN
  47888. >
  47889.      module.
  47890.     </P
  47891. ><P
  47892. >      <TABLE
  47893. WIDTH="100%"
  47894. BORDER="0"
  47895. CELLPADDING="0"
  47896. CELLSPACING="0"
  47897. CLASS="EXAMPLE"
  47898. ><TR
  47899. ><TD
  47900. ><DIV
  47901. CLASS="example"
  47902. ><A
  47903. NAME="AEN8010"
  47904. ></A
  47905. ><P
  47906. ><B
  47907. >Example 1. <B
  47908. CLASS="function"
  47909. >apache_request_headers()</B
  47910. > example</B
  47911. ></P
  47912. ><TABLE
  47913. BORDER="0"
  47914. BGCOLOR="#E0E0E0"
  47915. CELLPADDING="5"
  47916. ><TR
  47917. ><TD
  47918. ><PRE
  47919. CLASS="php"
  47920. ><?php
  47921. $headers = apache_request_headers();
  47922.  
  47923. foreach ($headers as $header => $value) {
  47924.     echo "$header: $value <br />\n";
  47925. }
  47926. ?></PRE
  47927. ></TD
  47928. ></TR
  47929. ></TABLE
  47930. ><P
  47931. >The above example will output 
  47932. something similar to:</P
  47933. ><TABLE
  47934. BORDER="0"
  47935. BGCOLOR="#E0E0E0"
  47936. CELLPADDING="5"
  47937. ><TR
  47938. ><TD
  47939. ><PRE
  47940. CLASS="screen"
  47941. >Accept: */*
  47942. Accept-Language: en-us
  47943. Accept-Encoding: gzip, deflate
  47944. User-Agent: Mozilla/4.0
  47945. Host: www.example.com
  47946. Connection: Keep-Alive</PRE
  47947. ></TD
  47948. ></TR
  47949. ></TABLE
  47950. ></DIV
  47951. ></TD
  47952. ></TR
  47953. ></TABLE
  47954. >
  47955.     </P
  47956. ><DIV
  47957. CLASS="note"
  47958. ><BLOCKQUOTE
  47959. CLASS="note"
  47960. ><P
  47961. ><B
  47962. >Note: </B
  47963. >
  47964.       Prior to PHP 4.3.0, <B
  47965. CLASS="function"
  47966. >apache_request_headers()</B
  47967. > was
  47968.       called <A
  47969. HREF="#function.getallheaders"
  47970. ><B
  47971. CLASS="function"
  47972. >getallheaders()</B
  47973. ></A
  47974. >.  After PHP 4.3.0,
  47975.       <A
  47976. HREF="#function.getallheaders"
  47977. ><B
  47978. CLASS="function"
  47979. >getallheaders()</B
  47980. ></A
  47981. > is an alias for
  47982.       <B
  47983. CLASS="function"
  47984. >apache_request_headers()</B
  47985. >.
  47986.      </P
  47987. ></BLOCKQUOTE
  47988. ></DIV
  47989. ><DIV
  47990. CLASS="note"
  47991. ><BLOCKQUOTE
  47992. CLASS="note"
  47993. ><P
  47994. ><B
  47995. >Note: </B
  47996. >
  47997.       You can also get at the value of the common CGI variables by
  47998.       reading them from the environment, which works whether or not
  47999.       you are using PHP as an <SPAN
  48000. CLASS="productname"
  48001. >Apache</SPAN
  48002. > module. Use
  48003.       <A
  48004. HREF="#function.phpinfo"
  48005. ><B
  48006. CLASS="function"
  48007. >phpinfo()</B
  48008. ></A
  48009. > to see a list of all of the available
  48010.       <A
  48011. HREF="#language.variables.predefined"
  48012. >environment variables</A
  48013. >.
  48014.      </P
  48015. ></BLOCKQUOTE
  48016. ></DIV
  48017. ><DIV
  48018. CLASS="note"
  48019. ><BLOCKQUOTE
  48020. CLASS="note"
  48021. ><P
  48022. ><B
  48023. >Note: </B
  48024. >As of PHP 4.3.3 you can use this function with the
  48025. <A
  48026. HREF="#ref.nsapi"
  48027. >NSAPI server module</A
  48028. > in Netscape/iPlanet/SunONE
  48029. webservers, too.</P
  48030. ></BLOCKQUOTE
  48031. ></DIV
  48032. ><P
  48033. >      See also <A
  48034. HREF="#function.apache-response-headers"
  48035. ><B
  48036. CLASS="function"
  48037. >apache_response_headers()</B
  48038. ></A
  48039. >.
  48040.     </P
  48041. ></DIV
  48042. ><H1
  48043. ><A
  48044. NAME="function.apache-reset-timeout"
  48045. ></A
  48046. >apache_reset_timeout</H1
  48047. ><DIV
  48048. CLASS="refnamediv"
  48049. ><A
  48050. NAME="AEN8033"
  48051. ></A
  48052. ><P
  48053. >    (no version information, might be only in CVS)</P
  48054. >apache_reset_timeout -- 
  48055.      Reset the Apache write timer
  48056.     </DIV
  48057. ><DIV
  48058. CLASS="refsect1"
  48059. ><A
  48060. NAME="AEN8036"
  48061. ></A
  48062. ><H2
  48063. >Description</H2
  48064. >bool <B
  48065. CLASS="methodname"
  48066. >apache_reset_timeout</B
  48067. > ( void )<BR
  48068. ></BR
  48069. ><P
  48070. >      <B
  48071. CLASS="function"
  48072. >apache_reset_timeout()</B
  48073. > resets the Apache write timer,
  48074.      which defaults to 300 seconds. With <VAR
  48075. CLASS="literal"
  48076. >set_time_limit(0);
  48077.       ignore_user_abort(true)</VAR
  48078. > and periodic
  48079.      <B
  48080. CLASS="function"
  48081. >apache_reset_timeout()</B
  48082. > calls, Apache can theoretically
  48083.      run forever.
  48084.     </P
  48085. ><P
  48086. >      Returns <TT
  48087. CLASS="constant"
  48088. ><B
  48089. >TRUE</B
  48090. ></TT
  48091. > on success or <TT
  48092. CLASS="constant"
  48093. ><B
  48094. >FALSE</B
  48095. ></TT
  48096. > on failure.
  48097.     </P
  48098. ><DIV
  48099. CLASS="note"
  48100. ><BLOCKQUOTE
  48101. CLASS="note"
  48102. ><P
  48103. ><B
  48104. >Note: </B
  48105. >
  48106.       This functions is just available for Apache 1.
  48107.      </P
  48108. ></BLOCKQUOTE
  48109. ></DIV
  48110. ><DIV
  48111. CLASS="note"
  48112. ><BLOCKQUOTE
  48113. CLASS="note"
  48114. ><P
  48115. ><B
  48116. >Note: </B
  48117. >This function is disabled in <A
  48118. HREF="#features.safe-mode"
  48119. >safe mode</A
  48120. >.</P
  48121. ></BLOCKQUOTE
  48122. ></DIV
  48123. ></DIV
  48124. ><H1
  48125. ><A
  48126. NAME="function.apache-response-headers"
  48127. ></A
  48128. >apache_response_headers</H1
  48129. ><DIV
  48130. CLASS="refnamediv"
  48131. ><A
  48132. NAME="AEN8055"
  48133. ></A
  48134. ><P
  48135. >    (PHP 4 >= 4.3.0, PHP 5)</P
  48136. >apache_response_headers -- 
  48137.      Fetch all HTTP response headers
  48138.     </DIV
  48139. ><DIV
  48140. CLASS="refsect1"
  48141. ><A
  48142. NAME="AEN8058"
  48143. ></A
  48144. ><H2
  48145. >Description</H2
  48146. >array <B
  48147. CLASS="methodname"
  48148. >apache_response_headers</B
  48149. > ( void )<BR
  48150. ></BR
  48151. ><P
  48152. >      Returns an array of all Apache response headers.
  48153.     </P
  48154. ><P
  48155. >      <TABLE
  48156. WIDTH="100%"
  48157. BORDER="0"
  48158. CELLPADDING="0"
  48159. CELLSPACING="0"
  48160. CLASS="EXAMPLE"
  48161. ><TR
  48162. ><TD
  48163. ><DIV
  48164. CLASS="example"
  48165. ><A
  48166. NAME="AEN8066"
  48167. ></A
  48168. ><P
  48169. ><B
  48170. >Example 1. <B
  48171. CLASS="function"
  48172. >apache_response_headers()</B
  48173. > example</B
  48174. ></P
  48175. ><TABLE
  48176. BORDER="0"
  48177. BGCOLOR="#E0E0E0"
  48178. CELLPADDING="5"
  48179. ><TR
  48180. ><TD
  48181. ><PRE
  48182. CLASS="php"
  48183. ><?php
  48184. print_r(apache_response_headers());
  48185. ?></PRE
  48186. ></TD
  48187. ></TR
  48188. ></TABLE
  48189. ><P
  48190. >The above example will output 
  48191. something similar to:</P
  48192. ><TABLE
  48193. BORDER="0"
  48194. BGCOLOR="#E0E0E0"
  48195. CELLPADDING="5"
  48196. ><TR
  48197. ><TD
  48198. ><PRE
  48199. CLASS="screen"
  48200. >Array
  48201. (
  48202.     [Accept-Ranges] => bytes
  48203.     [X-Powered-By] => PHP/4.3.8
  48204. )</PRE
  48205. ></TD
  48206. ></TR
  48207. ></TABLE
  48208. ></DIV
  48209. ></TD
  48210. ></TR
  48211. ></TABLE
  48212. >
  48213.     </P
  48214. ><DIV
  48215. CLASS="note"
  48216. ><BLOCKQUOTE
  48217. CLASS="note"
  48218. ><P
  48219. ><B
  48220. >Note: </B
  48221. >As of PHP 4.3.3 you can use this function with the
  48222. <A
  48223. HREF="#ref.nsapi"
  48224. >NSAPI server module</A
  48225. > in Netscape/iPlanet/SunONE
  48226. webservers, too.</P
  48227. ></BLOCKQUOTE
  48228. ></DIV
  48229. ><P
  48230. >      See also <A
  48231. HREF="#function.apache-request-headers"
  48232. ><B
  48233. CLASS="function"
  48234. >apache_request_headers()</B
  48235. ></A
  48236. >, and
  48237.      <A
  48238. HREF="#function.headers-sent"
  48239. ><B
  48240. CLASS="function"
  48241. >headers_sent()</B
  48242. ></A
  48243. >.
  48244.     </P
  48245. ></DIV
  48246. ><H1
  48247. ><A
  48248. NAME="function.apache-setenv"
  48249. ></A
  48250. >apache_setenv</H1
  48251. ><DIV
  48252. CLASS="refnamediv"
  48253. ><A
  48254. NAME="AEN8079"
  48255. ></A
  48256. ><P
  48257. >    (PHP 4 >= 4.2.0, PHP 5)</P
  48258. >apache_setenv -- Set an Apache subprocess_env variable</DIV
  48259. ><DIV
  48260. CLASS="refsect1"
  48261. ><A
  48262. NAME="AEN8082"
  48263. ></A
  48264. ><H2
  48265. >Description</H2
  48266. >int <B
  48267. CLASS="methodname"
  48268. >apache_setenv</B
  48269. > ( string variable, string value [, bool walk_to_top])<BR
  48270. ></BR
  48271. ><P
  48272. >      <B
  48273. CLASS="function"
  48274. >apache_setenv()</B
  48275. > sets the value of the Apache
  48276.      environment variable specified by
  48277.      <VAR
  48278. CLASS="parameter"
  48279. >variable</VAR
  48280. >.
  48281.     </P
  48282. ><DIV
  48283. CLASS="note"
  48284. ><BLOCKQUOTE
  48285. CLASS="note"
  48286. ><P
  48287. ><B
  48288. >Note: </B
  48289. >
  48290.       When setting an Apache environment variable, the corresponding $_SERVER
  48291.       variable is not changed.
  48292.      </P
  48293. ></BLOCKQUOTE
  48294. ></DIV
  48295. ><TABLE
  48296. WIDTH="100%"
  48297. BORDER="0"
  48298. CELLPADDING="0"
  48299. CELLSPACING="0"
  48300. CLASS="EXAMPLE"
  48301. ><TR
  48302. ><TD
  48303. ><DIV
  48304. CLASS="example"
  48305. ><A
  48306. NAME="AEN8101"
  48307. ></A
  48308. ><P
  48309. ><B
  48310. >Example 1. Setting an Apache environment variable using <B
  48311. CLASS="function"
  48312. >apache_setenv()</B
  48313. ></B
  48314. ></P
  48315. ><TABLE
  48316. BORDER="0"
  48317. BGCOLOR="#E0E0E0"
  48318. CELLPADDING="5"
  48319. ><TR
  48320. ><TD
  48321. ><PRE
  48322. CLASS="php"
  48323. ><?php
  48324. apache_setenv("EXAMPLE_VAR", "Example Value");
  48325. ?></PRE
  48326. ></TD
  48327. ></TR
  48328. ></TABLE
  48329. ></DIV
  48330. ></TD
  48331. ></TR
  48332. ></TABLE
  48333. ><P
  48334. >      <B
  48335. CLASS="function"
  48336. >apache_setenv()</B
  48337. > can be paired up with
  48338.      <A
  48339. HREF="#function.apache-getenv"
  48340. ><B
  48341. CLASS="function"
  48342. >apache_getenv()</B
  48343. ></A
  48344. > across separate pages or for setting
  48345.      variables to pass to Server Side Includes (.shtml) that have been
  48346.      included in PHP scripts.
  48347.     </P
  48348. ><P
  48349. >      See also <A
  48350. HREF="#function.apache-getenv"
  48351. ><B
  48352. CLASS="function"
  48353. >apache_getenv()</B
  48354. ></A
  48355. >.
  48356.     </P
  48357. ></DIV
  48358. ><H1
  48359. ><A
  48360. NAME="function.ascii2ebcdic"
  48361. ></A
  48362. >ascii2ebcdic</H1
  48363. ><DIV
  48364. CLASS="refnamediv"
  48365. ><A
  48366. NAME="AEN8111"
  48367. ></A
  48368. ><P
  48369. >    (PHP 3>= 3.0.17)</P
  48370. >ascii2ebcdic -- Translate string from ASCII to EBCDIC</DIV
  48371. ><DIV
  48372. CLASS="refsect1"
  48373. ><A
  48374. NAME="AEN8114"
  48375. ></A
  48376. ><H2
  48377. >Description</H2
  48378. >int <B
  48379. CLASS="methodname"
  48380. >ascii2ebcdic</B
  48381. > ( string ascii_str)<BR
  48382. ></BR
  48383. ><P
  48384. >      <B
  48385. CLASS="function"
  48386. >ascii2ebcdic()</B
  48387. > is an Apache-specific function which
  48388.      is available only on EBCDIC based operating systems (OS/390, BS2000).
  48389.      It translates the ASCII encoded string <VAR
  48390. CLASS="parameter"
  48391. >ascii_str</VAR
  48392. >
  48393.      to its equivalent EBCDIC representation (binary safe), and returns
  48394.      the result.
  48395.     </P
  48396. ><P
  48397. >      See also the reverse function <A
  48398. HREF="#function.ebcdic2ascii"
  48399. ><B
  48400. CLASS="function"
  48401. >ebcdic2ascii()</B
  48402. ></A
  48403. > 
  48404.     </P
  48405. ></DIV
  48406. ><H1
  48407. ><A
  48408. NAME="function.ebcdic2ascii"
  48409. ></A
  48410. >ebcdic2ascii</H1
  48411. ><DIV
  48412. CLASS="refnamediv"
  48413. ><A
  48414. NAME="AEN8128"
  48415. ></A
  48416. ><P
  48417. >    (PHP 3>= 3.0.17)</P
  48418. >ebcdic2ascii -- Translate string from EBCDIC to ASCII</DIV
  48419. ><DIV
  48420. CLASS="refsect1"
  48421. ><A
  48422. NAME="AEN8131"
  48423. ></A
  48424. ><H2
  48425. >Description</H2
  48426. >int <B
  48427. CLASS="methodname"
  48428. >ebcdic2ascii</B
  48429. > ( string ebcdic_str)<BR
  48430. ></BR
  48431. ><P
  48432. >      <B
  48433. CLASS="function"
  48434. >ebcdic2ascii()</B
  48435. > is an Apache-specific function which
  48436.      is available only on EBCDIC based operating systems (OS/390, BS2000).
  48437.      It translates the EBCDIC encoded string <VAR
  48438. CLASS="parameter"
  48439. >ebcdic_str</VAR
  48440. >
  48441.      to its equivalent ASCII representation (binary safe), and returns
  48442.      the result.
  48443.     </P
  48444. ><P
  48445. >      See also the reverse function <A
  48446. HREF="#function.ascii2ebcdic"
  48447. ><B
  48448. CLASS="function"
  48449. >ascii2ebcdic()</B
  48450. ></A
  48451. > 
  48452.     </P
  48453. ></DIV
  48454. ><H1
  48455. ><A
  48456. NAME="function.getallheaders"
  48457. ></A
  48458. >getallheaders</H1
  48459. ><DIV
  48460. CLASS="refnamediv"
  48461. ><A
  48462. NAME="AEN8145"
  48463. ></A
  48464. ><P
  48465. >    (PHP 3, PHP 4 , PHP 5)</P
  48466. >getallheaders -- Fetch all HTTP request headers</DIV
  48467. ><DIV
  48468. CLASS="refsect1"
  48469. ><A
  48470. NAME="AEN8148"
  48471. ></A
  48472. ><H2
  48473. >Description</H2
  48474. >array <B
  48475. CLASS="methodname"
  48476. >getallheaders</B
  48477. > ( void )<BR
  48478. ></BR
  48479. ><P
  48480. >      <B
  48481. CLASS="function"
  48482. >getallheaders()</B
  48483. > is an alias for
  48484.      <A
  48485. HREF="#function.apache-request-headers"
  48486. ><B
  48487. CLASS="function"
  48488. >apache_request_headers()</B
  48489. ></A
  48490. >.  It will return an
  48491.      associative array of all the HTTP headers in the current request.
  48492.      Please read the <A
  48493. HREF="#function.apache-request-headers"
  48494. ><B
  48495. CLASS="function"
  48496. >apache_request_headers()</B
  48497. ></A
  48498. >
  48499.      documentation for more information on how this function works.
  48500.     </P
  48501. ><DIV
  48502. CLASS="note"
  48503. ><BLOCKQUOTE
  48504. CLASS="note"
  48505. ><P
  48506. ><B
  48507. >Note: </B
  48508. >
  48509.       In PHP 4.3.0, <B
  48510. CLASS="function"
  48511. >getallheaders()</B
  48512. > became an
  48513.       alias for <A
  48514. HREF="#function.apache-request-headers"
  48515. ><B
  48516. CLASS="function"
  48517. >apache_request_headers()</B
  48518. ></A
  48519. >.
  48520.       Essentially, it was renamed.  This is because this function
  48521.       only works when PHP is compiled as an
  48522.       <SPAN
  48523. CLASS="productname"
  48524. >Apache</SPAN
  48525. > Module.
  48526.      </P
  48527. ></BLOCKQUOTE
  48528. ></DIV
  48529. ><DIV
  48530. CLASS="note"
  48531. ><BLOCKQUOTE
  48532. CLASS="note"
  48533. ><P
  48534. ><B
  48535. >Note: </B
  48536. >As of PHP 4.3.3 you can use this function with the
  48537. <A
  48538. HREF="#ref.nsapi"
  48539. >NSAPI server module</A
  48540. > in Netscape/iPlanet/SunONE
  48541. webservers, too.</P
  48542. ></BLOCKQUOTE
  48543. ></DIV
  48544. ><P
  48545. >      See also <A
  48546. HREF="#function.apache-request-headers"
  48547. ><B
  48548. CLASS="function"
  48549. >apache_request_headers()</B
  48550. ></A
  48551. >.
  48552.     </P
  48553. ></DIV
  48554. ><H1
  48555. ><A
  48556. NAME="function.virtual"
  48557. ></A
  48558. >virtual</H1
  48559. ><DIV
  48560. CLASS="refnamediv"
  48561. ><A
  48562. NAME="AEN8169"
  48563. ></A
  48564. ><P
  48565. >    (PHP 3, PHP 4 , PHP 5)</P
  48566. >virtual -- Perform an Apache sub-request</DIV
  48567. ><DIV
  48568. CLASS="refsect1"
  48569. ><A
  48570. NAME="AEN8172"
  48571. ></A
  48572. ><H2
  48573. >Description</H2
  48574. >int <B
  48575. CLASS="methodname"
  48576. >virtual</B
  48577. > ( string filename)<BR
  48578. ></BR
  48579. ><P
  48580. >      <B
  48581. CLASS="function"
  48582. >virtual()</B
  48583. > is an Apache-specific function which
  48584.      is equivalent to <!--#include virtual...--> in mod_include.
  48585.      It performs an Apache sub-request.  It is useful for including
  48586.      CGI scripts or .shtml files, or anything else that you would
  48587.      parse through Apache.  Note that for a CGI script, the script
  48588.      must generate valid CGI headers.  At the minimum that means it
  48589.      must generate a Content-type header.
  48590.     </P
  48591. ><P
  48592. >      To run the sub-request, all buffers are terminated and flushed to the
  48593.      browser, pending headers are sent too.
  48594.     </P
  48595. ><DIV
  48596. CLASS="warning"
  48597. ><P
  48598. ></P
  48599. ><TABLE
  48600. CLASS="warning"
  48601. BORDER="1"
  48602. WIDTH="100%"
  48603. ><TR
  48604. ><TD
  48605. ALIGN="CENTER"
  48606. ><B
  48607. >Warning</B
  48608. ></TD
  48609. ></TR
  48610. ><TR
  48611. ><TD
  48612. ALIGN="LEFT"
  48613. ><P
  48614. >       This function works only when PHP is compiled as an Apache module,
  48615.       since it uses the Apache API for doing sub requests. Query string can be
  48616.       passed to the included file but <VAR
  48617. CLASS="varname"
  48618. >$_GET</VAR
  48619. > is copied from
  48620.       the parent script and only <VAR
  48621. CLASS="varname"
  48622. >$_SERVER['QUERY_STRING']</VAR
  48623. > is
  48624.       filled with the passed query string. The query string may only be passed
  48625.       when using Apache 2. The requested file will not be listed in the Apache access log.
  48626.      </P
  48627. ></TD
  48628. ></TR
  48629. ></TABLE
  48630. ></DIV
  48631. ><P
  48632. >      As of PHP 4.0.6, you can use <B
  48633. CLASS="function"
  48634. >virtual()</B
  48635. > on PHP files.
  48636.      However, it is typically better to use <A
  48637. HREF="#function.include"
  48638. ><B
  48639. CLASS="function"
  48640. >include()</B
  48641. ></A
  48642. > or
  48643.      <A
  48644. HREF="#function.require"
  48645. ><B
  48646. CLASS="function"
  48647. >require()</B
  48648. ></A
  48649. > if you need to include another PHP file.
  48650.     </P
  48651. ><DIV
  48652. CLASS="note"
  48653. ><BLOCKQUOTE
  48654. CLASS="note"
  48655. ><P
  48656. ><B
  48657. >Note: </B
  48658. >As of PHP 4.3.3 you can use this function with the
  48659. <A
  48660. HREF="#ref.nsapi"
  48661. >NSAPI server module</A
  48662. > in Netscape/iPlanet/SunONE
  48663. webservers, too.</P
  48664. ></BLOCKQUOTE
  48665. ></DIV
  48666. ></DIV
  48667. ></DIV
  48668. ><DIV
  48669. CLASS="reference"
  48670. ><A
  48671. NAME="ref.apd"
  48672. ></A
  48673. ><DIV
  48674. CLASS="TITLEPAGE"
  48675. ><H1
  48676. CLASS="title"
  48677. >II. Advanced PHP debugger</H1
  48678. ><DIV
  48679. CLASS="PARTINTRO"
  48680. ><A
  48681. NAME="AEN8197"
  48682. ></A
  48683. ><DIV
  48684. CLASS="section"
  48685. ><H2
  48686. CLASS="section"
  48687. ><A
  48688. NAME="apd.intro"
  48689. >Introduction</A
  48690. ></H2
  48691. ><P
  48692. >      APD is the Advanced PHP Debugger. It was written to provide profiling and
  48693.      debugging capabilities for PHP code, as well as to provide the ability to
  48694.      print out a full stack backtrace. APD supports interactive debugging, but
  48695.      by default it writes data to trace files. It also offers event based
  48696.      logging so that varying levels of information (including function calls,
  48697.      arguments passed, timings, etc.) can be turned on or off for individual
  48698.      scripts.
  48699.     <DIV
  48700. CLASS="caution"
  48701. ><P
  48702. ></P
  48703. ><TABLE
  48704. CLASS="caution"
  48705. BORDER="1"
  48706. WIDTH="100%"
  48707. ><TR
  48708. ><TD
  48709. ALIGN="CENTER"
  48710. ><B
  48711. >Caution</B
  48712. ></TD
  48713. ></TR
  48714. ><TR
  48715. ><TD
  48716. ALIGN="LEFT"
  48717. ><P
  48718. >      APD is a Zend Extension, modifying the way the internals of PHP handle 
  48719.      function calls, and thus may or may not be compatible with other Zend 
  48720.      Extensions (for example Zend Optimizer). 
  48721.     </P
  48722. ></TD
  48723. ></TR
  48724. ></TABLE
  48725. ></DIV
  48726. >
  48727.     </P
  48728. ></DIV
  48729. ><DIV
  48730. CLASS="section"
  48731. ><HR><H2
  48732. CLASS="section"
  48733. ><A
  48734. NAME="apd.installation"
  48735. >Installation</A
  48736. ></H2
  48737. ><P
  48738. >   APD is currently available as a PECL extension from 
  48739.   <A
  48740. HREF="http://pecl.php.net/package/apd"
  48741. TARGET="_top"
  48742. >http://pecl.php.net/package/apd</A
  48743. >.
  48744.   Make sure you have installed the CGI version of PHP and it is available
  48745.   in your current path along with the phpize script.
  48746.  </P
  48747. ><P
  48748. >   Run the following command to download, build, and install the latest stable
  48749.   version of APD:
  48750.  <TABLE
  48751. BORDER="0"
  48752. BGCOLOR="#E0E0E0"
  48753. CELLPADDING="5"
  48754. ><TR
  48755. ><TD
  48756. ><PRE
  48757. CLASS="screen"
  48758. >pear install apd</PRE
  48759. ></TD
  48760. ></TR
  48761. ></TABLE
  48762. >
  48763.  </P
  48764. ><P
  48765. >   This automatically installs the APD Zend module into your PHP
  48766.   extensions directory. It is not mandatory to keep it there; you can
  48767.   store the module in any directory PHP can read as long as you set
  48768.   the zend_extension parameter accordingly.
  48769.  </P
  48770. ><P
  48771. >   Windows users can download the extension dll <TT
  48772. CLASS="filename"
  48773. >php_apd.dll</TT
  48774. >
  48775.   from <A
  48776. HREF="http://snaps.php.net/win32/PECL_STABLE/"
  48777. TARGET="_top"
  48778. >http://snaps.php.net/win32/PECL_STABLE/</A
  48779. >.
  48780.  </P
  48781. ><P
  48782. >   In your INI file, add the following lines:
  48783.  </P
  48784. ><P
  48785. >   <TABLE
  48786. BORDER="0"
  48787. BGCOLOR="#E0E0E0"
  48788. CELLPADDING="5"
  48789. ><TR
  48790. ><TD
  48791. ><PRE
  48792. CLASS="php.ini"
  48793. >zend_extension = /absolute/path/to/apd.so
  48794. apd.dumpdir = /absolute/path/to/trace/directory
  48795. apd.statement_trace = 0</PRE
  48796. ></TD
  48797. ></TR
  48798. ></TABLE
  48799. >
  48800.  </P
  48801. ><P
  48802. >   Depending on your PHP build, the zend_extension directive can be one of the
  48803.   following:
  48804.  </P
  48805. ><P
  48806. >   <TABLE
  48807. BORDER="0"
  48808. BGCOLOR="#E0E0E0"
  48809. CELLPADDING="5"
  48810. ><TR
  48811. ><TD
  48812. ><PRE
  48813. CLASS="script"
  48814. >zend_extension              (non ZTS, non debug build)
  48815. zend_extension_ts           (    ZTS, non debug build)
  48816. zend_extension_debug        (non ZTS,     debug build)
  48817. zend_extension_debug_ts     (    ZTS,     debug build)</PRE
  48818. ></TD
  48819. ></TR
  48820. ></TABLE
  48821. >
  48822.  </P
  48823. ></DIV
  48824. ><DIV
  48825. CLASS="section"
  48826. ><HR><H2
  48827. CLASS="section"
  48828. ><A
  48829. NAME="apd.installwin32"
  48830. >Building on Win32</A
  48831. ></H2
  48832. ><P
  48833. >   To build APD under Windows you need a working PHP compilation
  48834.   environment as described on http://php.net/ -- basically, it requires
  48835.   you to have Microsoft Visual C++, win32build.zip, bison/flex, and some know how
  48836.   to get it to work. Also ensure that adp.dsp has DOS line endings; if it has unix
  48837.   line endings, Microsoft Visual C++ will complain about it.
  48838.  </P
  48839. ></DIV
  48840. ><DIV
  48841. CLASS="section"
  48842. ><HR><H2
  48843. CLASS="section"
  48844. ><A
  48845. NAME="apd.configuration"
  48846. >Runtime Configuration</A
  48847. ></H2
  48848. ><P
  48849. >Here's a short explanation of
  48850. the configuration directives.</P
  48851. ><P
  48852. >   <P
  48853. ></P
  48854. ><DIV
  48855. CLASS="variablelist"
  48856. ><DL
  48857. ><DT
  48858. ><A
  48859. NAME="ini.apd.dumpdir"
  48860. ></A
  48861. ><VAR
  48862. CLASS="parameter"
  48863. >apd.dumpdir</VAR
  48864. >
  48865.      <A
  48866. HREF="#language.types.string"
  48867. ><B
  48868. CLASS="type"
  48869. >string</B
  48870. ></A
  48871. ></DT
  48872. ><DD
  48873. ><P
  48874. >       Sets the directory in which APD writes profile dump files.
  48875.       You can specify an absolute path or a relative path.
  48876.      </P
  48877. ><P
  48878. >       You can specify a different directory as an argument
  48879.       to <A
  48880. HREF="#function.apd-set-pprof-trace"
  48881. ><B
  48882. CLASS="function"
  48883. >apd_set_pprof_trace()</B
  48884. ></A
  48885. >.
  48886.      </P
  48887. ></DD
  48888. ><DT
  48889. ><A
  48890. NAME="ini.apd.statement-trace"
  48891. ></A
  48892. ><VAR
  48893. CLASS="parameter"
  48894. >apd.statement_trace</VAR
  48895. >
  48896.      <A
  48897. HREF="#language.types.boolean"
  48898. ><B
  48899. CLASS="type"
  48900. >boolean</B
  48901. ></A
  48902. ></DT
  48903. ><DD
  48904. ><P
  48905. >      Specfies whether or not to do per-line tracings. Turning this on (1) will
  48906.      impact the performance of your application.
  48907.      </P
  48908. ></DD
  48909. ></DL
  48910. ></DIV
  48911. >
  48912.  </P
  48913. ></DIV
  48914. ><DIV
  48915. CLASS="section"
  48916. ><HR><H2
  48917. CLASS="section"
  48918. ><A
  48919. NAME="apd.resources"
  48920. >Resource Types</A
  48921. ></H2
  48922. ><P
  48923. >This extension has no resource types defined.</P
  48924. ></DIV
  48925. ><DIV
  48926. CLASS="section"
  48927. ><HR><H2
  48928. CLASS="section"
  48929. ><A
  48930. NAME="apd.constants"
  48931. >Predefined Constants</A
  48932. ></H2
  48933. ><P
  48934. >This extension has no constants defined.</P
  48935. ></DIV
  48936. ><DIV
  48937. CLASS="section"
  48938. ><HR><H2
  48939. CLASS="section"
  48940. ><A
  48941. NAME="apd.examples"
  48942. >How to use PHP-APD in your scripts</A
  48943. ></H2
  48944. ><DIV
  48945. CLASS="procedure"
  48946. ><OL
  48947. TYPE="1"
  48948. ><LI
  48949. ><P
  48950. >       As the first line of your PHP script, call the apd_set_pprof_trace() function
  48951.       to start the trace:
  48952.      </P
  48953. ><P
  48954. >       <TABLE
  48955. BORDER="0"
  48956. BGCOLOR="#E0E0E0"
  48957. CELLPADDING="5"
  48958. ><TR
  48959. ><TD
  48960. ><PRE
  48961. CLASS="php"
  48962. >apd_set_pprof_trace();</PRE
  48963. ></TD
  48964. ></TR
  48965. ></TABLE
  48966. >
  48967.      </P
  48968. ><P
  48969. >      You can insert the line anywhere in your script, but if you do not start
  48970.      tracing at the beginning of your script you discard profile data that might
  48971.      otherwise lead you to a performance bottleneck.
  48972.      </P
  48973. ></LI
  48974. ><LI
  48975. ><P
  48976. >       Now run your script. The dump output will be written to
  48977.       <TT
  48978. CLASS="filename"
  48979. >apd.dumpdir/pprof_pid.ext</TT
  48980. >.
  48981.       <DIV
  48982. CLASS="tip"
  48983. ><BLOCKQUOTE
  48984. CLASS="tip"
  48985. ><P
  48986. ><B
  48987. >Tip: </B
  48988. >
  48989.         If you're running the CGI version of PHP, you will need to add the '-e'
  48990.         flag to enable extended information for apd to work properly. For
  48991.         example: 
  48992.         <KBD
  48993. CLASS="userinput"
  48994. >php -e -f script.php</KBD
  48995. >
  48996.       </P
  48997. ></BLOCKQUOTE
  48998. ></DIV
  48999. >
  49000.      </P
  49001. ></LI
  49002. ><LI
  49003. ><P
  49004. >       To display formatted profile data, issue the <B
  49005. CLASS="command"
  49006. >pprofp</B
  49007. >
  49008.       command with the sort and display options of your choice. The formatted
  49009.       output will look something like:
  49010.       <TABLE
  49011. BORDER="0"
  49012. BGCOLOR="#E0E0E0"
  49013. CELLPADDING="5"
  49014. ><TR
  49015. ><TD
  49016. ><PRE
  49017. CLASS="screen"
  49018. >bash-2.05b$ pprofp -R /tmp/pprof.22141.0
  49019.  
  49020. Trace for /home/dan/testapd.php
  49021. Total Elapsed Time = 0.00
  49022. Total System Time  = 0.00
  49023. Total User Time    = 0.00
  49024.  
  49025.  
  49026. Real         User        System             secs/    cumm
  49027. %Time (excl/cumm)  (excl/cumm)  (excl/cumm) Calls    call    s/call  Memory Usage Name
  49028. --------------------------------------------------------------------------------------
  49029. 100.0 0.00 0.00  0.00 0.00  0.00 0.00     1  0.0000   0.0009            0 main
  49030. 56.9 0.00 0.00  0.00 0.00  0.00 0.00     1  0.0005   0.0005            0 apd_set_pprof_trace
  49031. 28.0 0.00 0.00  0.00 0.00  0.00 0.00    10  0.0000   0.0000            0 preg_replace
  49032. 14.3 0.00 0.00  0.00 0.00  0.00 0.00    10  0.0000   0.0000            0 str_replace</PRE
  49033. ></TD
  49034. ></TR
  49035. ></TABLE
  49036. >
  49037.      </P
  49038. ><P
  49039. >      The -R option used in this example sorts the profile table by the amount
  49040.      of real time the script spent executing a given function. The "cumm call"
  49041.      column reveals how many times each function was called, and the "s/call"
  49042.      column reveals how many seconds each call to the function required, on
  49043.      average.
  49044.      </P
  49045. ></LI
  49046. ><LI
  49047. ><P
  49048. >      To generate a calltree file that you can import into the KCacheGrind
  49049.      profile analysis application, issue the <B
  49050. CLASS="command"
  49051. >pprof2calltree</B
  49052. >
  49053.      comand.
  49054.      </P
  49055. ></LI
  49056. ></OL
  49057. ></DIV
  49058. ></DIV
  49059. ><DIV
  49060. CLASS="section"
  49061. ><HR><H2
  49062. CLASS="section"
  49063. ><A
  49064. NAME="apd.contact"
  49065. >Contact information</A
  49066. ></H2
  49067. ><P
  49068. >       If you have comments, bugfixes, enhancements or want to help developing 
  49069.       this beast, you can send an mail to 
  49070.       <A
  49071. HREF="mailto:apd@mail.communityconnect.com"
  49072. TARGET="_top"
  49073. >apd@mail.communityconnect.com</A
  49074. >. Any help is very 
  49075.       welcome.
  49076.      </P
  49077. ></DIV
  49078. ></DIV
  49079. ><DIV
  49080. CLASS="TOC"
  49081. ><DL
  49082. ><DT
  49083. ><B
  49084. >Table of Contents</B
  49085. ></DT
  49086. ><DT
  49087. ><A
  49088. HREF="#function.apd-breakpoint"
  49089. >apd_breakpoint</A
  49090. > -- Stops the interpreter and waits on a CR from the socket</DT
  49091. ><DT
  49092. ><A
  49093. HREF="#function.apd-callstack"
  49094. >apd_callstack</A
  49095. > -- Returns the current call stack as an array</DT
  49096. ><DT
  49097. ><A
  49098. HREF="#function.apd-clunk"
  49099. >apd_clunk</A
  49100. > -- Throw a warning and a callstack</DT
  49101. ><DT
  49102. ><A
  49103. HREF="#function.apd-continue"
  49104. >apd_continue</A
  49105. > -- Restarts the interpreter</DT
  49106. ><DT
  49107. ><A
  49108. HREF="#function.apd-croak"
  49109. >apd_croak</A
  49110. > -- Throw an error, a callstack and then exit</DT
  49111. ><DT
  49112. ><A
  49113. HREF="#function.apd-dump-function-table"
  49114. >apd_dump_function_table</A
  49115. > -- Outputs the current function table</DT
  49116. ><DT
  49117. ><A
  49118. HREF="#function.apd-dump-persistent-resources"
  49119. >apd_dump_persistent_resources</A
  49120. > -- Return all persistent resources as an array</DT
  49121. ><DT
  49122. ><A
  49123. HREF="#function.apd-dump-regular-resources"
  49124. >apd_dump_regular_resources</A
  49125. > -- Return all current regular resources as an array</DT
  49126. ><DT
  49127. ><A
  49128. HREF="#function.apd-echo"
  49129. >apd_echo</A
  49130. > -- Echo to the debugging socket</DT
  49131. ><DT
  49132. ><A
  49133. HREF="#function.apd-get-active-symbols"
  49134. >apd_get_active_symbols</A
  49135. > -- Get an array of the current variables names in the local scope</DT
  49136. ><DT
  49137. ><A
  49138. HREF="#function.apd-set-pprof-trace"
  49139. >apd_set_pprof_trace</A
  49140. > -- Starts the session debugging</DT
  49141. ><DT
  49142. ><A
  49143. HREF="#function.apd-set-session-trace"
  49144. >apd_set_session_trace</A
  49145. > -- Starts the session debugging</DT
  49146. ><DT
  49147. ><A
  49148. HREF="#function.apd-set-session"
  49149. >apd_set_session</A
  49150. > -- Changes or sets the current debugging level</DT
  49151. ><DT
  49152. ><A
  49153. HREF="#function.apd-set-socket-session-trace"
  49154. >apd_set_socket_session_trace</A
  49155. > -- Starts the remote session debugging</DT
  49156. ><DT
  49157. ><A
  49158. HREF="#function.override-function"
  49159. >override_function</A
  49160. > -- Overrides built-in functions</DT
  49161. ><DT
  49162. ><A
  49163. HREF="#function.rename-function"
  49164. >rename_function</A
  49165. > -- Renames orig_name to new_name in the global function_table</DT
  49166. ></DL
  49167. ></DIV
  49168. ></DIV
  49169. ><H1
  49170. ><A
  49171. NAME="function.apd-breakpoint"
  49172. ></A
  49173. >apd_breakpoint</H1
  49174. ><DIV
  49175. CLASS="refnamediv"
  49176. ><A
  49177. NAME="AEN8274"
  49178. ></A
  49179. ><P
  49180. >    (no version information, might be only in CVS)</P
  49181. >apd_breakpoint -- Stops the interpreter and waits on a CR from the socket</DIV
  49182. ><DIV
  49183. CLASS="refsect1"
  49184. ><A
  49185. NAME="AEN8277"
  49186. ></A
  49187. ><H2
  49188. >Description</H2
  49189. >void <B
  49190. CLASS="methodname"
  49191. >apd_breakpoint</B
  49192. > ( int debug_level)<BR
  49193. ></BR
  49194. ><P
  49195. >      This can be used to stop the running of your script, and await responses 
  49196.      on the connected socket.  To step the program, just send enter (a blank 
  49197.      line), or enter a php command to be executed.  A typical session using 
  49198.      tcplisten would look like this.
  49199.     </P
  49200. ><P
  49201. >      <TABLE
  49202. BORDER="0"
  49203. BGCOLOR="#E0E0E0"
  49204. CELLPADDING="5"
  49205. ><TR
  49206. ><TD
  49207. ><PRE
  49208. CLASS="shell"
  49209. >bash#tcplisten localhost 7777
  49210.  
  49211. APD - Advanced PHP Debugger Trace File
  49212. ---------------------------------------------------------------------------
  49213. Process Pid (6118)
  49214. Trace Begun at Sun Mar 10 23:13:12 2002
  49215. ---------------------------------------------------------------------------
  49216. (  0.000000): apd_set_session_trace called at /home/alan/Projects/project2/test. 
  49217. php:5
  49218. (  0.074824): apd_set_session_trace_socket() at /home/alan/Projects/project2/tes 
  49219. t.php:5 returned.  Elapsed (0.074824)
  49220. (  0.074918): apd_breakpoint() /home/alan/Projects/project2/test.php:7
  49221.               ++ argv[0] $(??) = 9
  49222. apd_breakpoint() at /home/alan/Projects/project2/test.php:7 returned.  Elapsed ( 
  49223. -2089521468.1073275368)
  49224. >\n 
  49225. statement: /home/alan/Projects/project2/test.php:8
  49226. >\n 
  49227. statement: /home/alan/Projects/project2/test.php:8
  49228. >\n 
  49229. statement: /home/alan/Projects/project2/test.php:10
  49230. >apd_echo($i);
  49231. EXEC: apd_echo($i);
  49232. 0
  49233. >apd_echo(serialize(apd_get_active_symbols()));
  49234. EXEC:  apd_echo(serialize(apd_get_active_symbols()));
  49235. a:47:{i:0;s:4:"PWD";i:1;s:10:"COLORFGBG";i:2;s:11:"XAUTHORITY";i:3;s:14:"
  49236. COLORTERM_BCE";i:4;s:9:"WINDOWID";i:5;s:14:"ETERM_VERSION";i:6;s:16:"SE
  49237. SSION_MANAGER";i:7;s:4:"PS1";i:8;s:11:"GDMSESSION";i:9;s:5:"USER";i:10;s:5:"
  49238. MAIL";i:11;s:7:"OLDPWD";i:12;s:5:"LANG";i:13;s:10:"COLORTERM";i:14;s:8:"DISP
  49239. LAY";i:15;s:8:"LOGNAME";i:16;s:6:"
  49240. >apd_echo(system('ls /home/mydir'));
  49241. ........
  49242. >apd_continue(0);</PRE
  49243. ></TD
  49244. ></TR
  49245. ></TABLE
  49246. >
  49247.     </P
  49248. ></DIV
  49249. ><H1
  49250. ><A
  49251. NAME="function.apd-callstack"
  49252. ></A
  49253. >apd_callstack</H1
  49254. ><DIV
  49255. CLASS="refnamediv"
  49256. ><A
  49257. NAME="AEN8289"
  49258. ></A
  49259. ><P
  49260. >    (no version information, might be only in CVS)</P
  49261. >apd_callstack -- Returns the current call stack as an array</DIV
  49262. ><DIV
  49263. CLASS="refsect1"
  49264. ><A
  49265. NAME="AEN8292"
  49266. ></A
  49267. ><H2
  49268. >Description</H2
  49269. >array <B
  49270. CLASS="methodname"
  49271. >apd_callstack</B
  49272. > ( void )<BR
  49273. ></BR
  49274. ><P
  49275. >      Returns the current call stack as an array
  49276.     </P
  49277. ><P
  49278. >      <TABLE
  49279. WIDTH="100%"
  49280. BORDER="0"
  49281. CELLPADDING="0"
  49282. CELLSPACING="0"
  49283. CLASS="EXAMPLE"
  49284. ><TR
  49285. ><TD
  49286. ><DIV
  49287. CLASS="example"
  49288. ><A
  49289. NAME="AEN8300"
  49290. ></A
  49291. ><P
  49292. ><B
  49293. >Example 1. <B
  49294. CLASS="function"
  49295. >apd_callstack()</B
  49296. > example</B
  49297. ></P
  49298. ><TABLE
  49299. BORDER="0"
  49300. BGCOLOR="#E0E0E0"
  49301. CELLPADDING="5"
  49302. ><TR
  49303. ><TD
  49304. ><PRE
  49305. CLASS="php"
  49306. ><?php
  49307. print_r(apd_callstack());
  49308. ?></PRE
  49309. ></TD
  49310. ></TR
  49311. ></TABLE
  49312. ></DIV
  49313. ></TD
  49314. ></TR
  49315. ></TABLE
  49316. >
  49317.     </P
  49318. ></DIV
  49319. ><H1
  49320. ><A
  49321. NAME="function.apd-clunk"
  49322. ></A
  49323. >apd_clunk</H1
  49324. ><DIV
  49325. CLASS="refnamediv"
  49326. ><A
  49327. NAME="AEN8305"
  49328. ></A
  49329. ><P
  49330. >    (no version information, might be only in CVS)</P
  49331. >apd_clunk -- Throw a warning and a callstack</DIV
  49332. ><DIV
  49333. CLASS="refsect1"
  49334. ><A
  49335. NAME="AEN8308"
  49336. ></A
  49337. ><H2
  49338. >Description</H2
  49339. >void <B
  49340. CLASS="methodname"
  49341. >apd_clunk</B
  49342. > ( string warning [, string delimiter])<BR
  49343. ></BR
  49344. ><P
  49345. >      Behaves like perl's Carp::cluck. Throw a warning and a callstack.
  49346.      The default line delimiter is "<BR />\n".
  49347.     </P
  49348. ><P
  49349. >      <TABLE
  49350. WIDTH="100%"
  49351. BORDER="0"
  49352. CELLPADDING="0"
  49353. CELLSPACING="0"
  49354. CLASS="EXAMPLE"
  49355. ><TR
  49356. ><TD
  49357. ><DIV
  49358. CLASS="example"
  49359. ><A
  49360. NAME="AEN8321"
  49361. ></A
  49362. ><P
  49363. ><B
  49364. >Example 1. <B
  49365. CLASS="function"
  49366. >apd_clunk()</B
  49367. > example</B
  49368. ></P
  49369. ><TABLE
  49370. BORDER="0"
  49371. BGCOLOR="#E0E0E0"
  49372. CELLPADDING="5"
  49373. ><TR
  49374. ><TD
  49375. ><PRE
  49376. CLASS="php"
  49377. ><?php
  49378. apd_clunk("Some Warning","<P>");
  49379. ?></PRE
  49380. ></TD
  49381. ></TR
  49382. ></TABLE
  49383. ></DIV
  49384. ></TD
  49385. ></TR
  49386. ></TABLE
  49387. >
  49388.     </P
  49389. ></DIV
  49390. ><H1
  49391. ><A
  49392. NAME="function.apd-continue"
  49393. ></A
  49394. >apd_continue</H1
  49395. ><DIV
  49396. CLASS="refnamediv"
  49397. ><A
  49398. NAME="AEN8326"
  49399. ></A
  49400. ><P
  49401. >    (no version information, might be only in CVS)</P
  49402. >apd_continue -- Restarts the interpreter</DIV
  49403. ><DIV
  49404. CLASS="refsect1"
  49405. ><A
  49406. NAME="AEN8329"
  49407. ></A
  49408. ><H2
  49409. >Description</H2
  49410. >void <B
  49411. CLASS="methodname"
  49412. >apd_continue</B
  49413. > ( int debug_level)<BR
  49414. ></BR
  49415. ><P
  49416. >      Usually sent via the socket to restart the interpreter.
  49417.     </P
  49418. ><P
  49419. >      <TABLE
  49420. WIDTH="100%"
  49421. BORDER="0"
  49422. CELLPADDING="0"
  49423. CELLSPACING="0"
  49424. CLASS="EXAMPLE"
  49425. ><TR
  49426. ><TD
  49427. ><DIV
  49428. CLASS="example"
  49429. ><A
  49430. NAME="AEN8339"
  49431. ></A
  49432. ><P
  49433. ><B
  49434. >Example 1. <B
  49435. CLASS="function"
  49436. >apd_continue()</B
  49437. > example</B
  49438. ></P
  49439. ><TABLE
  49440. BORDER="0"
  49441. BGCOLOR="#E0E0E0"
  49442. CELLPADDING="5"
  49443. ><TR
  49444. ><TD
  49445. ><PRE
  49446. CLASS="php"
  49447. ><?php
  49448. apd_continue(0);
  49449. ?></PRE
  49450. ></TD
  49451. ></TR
  49452. ></TABLE
  49453. ></DIV
  49454. ></TD
  49455. ></TR
  49456. ></TABLE
  49457. >
  49458.     </P
  49459. ></DIV
  49460. ><H1
  49461. ><A
  49462. NAME="function.apd-croak"
  49463. ></A
  49464. >apd_croak</H1
  49465. ><DIV
  49466. CLASS="refnamediv"
  49467. ><A
  49468. NAME="AEN8344"
  49469. ></A
  49470. ><P
  49471. >    (no version information, might be only in CVS)</P
  49472. >apd_croak -- Throw an error, a callstack and then exit</DIV
  49473. ><DIV
  49474. CLASS="refsect1"
  49475. ><A
  49476. NAME="AEN8347"
  49477. ></A
  49478. ><H2
  49479. >Description</H2
  49480. >void <B
  49481. CLASS="methodname"
  49482. >apd_croak</B
  49483. > ( string warning [, string delimiter])<BR
  49484. ></BR
  49485. ><P
  49486. >      Behaves like perl's Carp::croak. Throw an error, a callstack and then
  49487.      exit.  The default line delimiter is "<BR />\n".
  49488.     </P
  49489. ><P
  49490. >      <TABLE
  49491. WIDTH="100%"
  49492. BORDER="0"
  49493. CELLPADDING="0"
  49494. CELLSPACING="0"
  49495. CLASS="EXAMPLE"
  49496. ><TR
  49497. ><TD
  49498. ><DIV
  49499. CLASS="example"
  49500. ><A
  49501. NAME="AEN8360"
  49502. ></A
  49503. ><P
  49504. ><B
  49505. >Example 1. <B
  49506. CLASS="function"
  49507. >apd_croak()</B
  49508. > example</B
  49509. ></P
  49510. ><TABLE
  49511. BORDER="0"
  49512. BGCOLOR="#E0E0E0"
  49513. CELLPADDING="5"
  49514. ><TR
  49515. ><TD
  49516. ><PRE
  49517. CLASS="php"
  49518. ><?php
  49519. apd_croak("Some Warning","<P>");
  49520. ?></PRE
  49521. ></TD
  49522. ></TR
  49523. ></TABLE
  49524. ></DIV
  49525. ></TD
  49526. ></TR
  49527. ></TABLE
  49528. >
  49529.     </P
  49530. ></DIV
  49531. ><H1
  49532. ><A
  49533. NAME="function.apd-dump-function-table"
  49534. ></A
  49535. >apd_dump_function_table</H1
  49536. ><DIV
  49537. CLASS="refnamediv"
  49538. ><A
  49539. NAME="AEN8365"
  49540. ></A
  49541. ><P
  49542. >    (no version information, might be only in CVS)</P
  49543. >apd_dump_function_table -- Outputs the current function table</DIV
  49544. ><DIV
  49545. CLASS="refsect1"
  49546. ><A
  49547. NAME="AEN8368"
  49548. ></A
  49549. ><H2
  49550. >Description</H2
  49551. >void <B
  49552. CLASS="methodname"
  49553. >apd_dump_function_table</B
  49554. > ( void )<BR
  49555. ></BR
  49556. ><P
  49557. >      Outputs the current function table.
  49558.     </P
  49559. ><P
  49560. >      <TABLE
  49561. WIDTH="100%"
  49562. BORDER="0"
  49563. CELLPADDING="0"
  49564. CELLSPACING="0"
  49565. CLASS="EXAMPLE"
  49566. ><TR
  49567. ><TD
  49568. ><DIV
  49569. CLASS="example"
  49570. ><A
  49571. NAME="AEN8376"
  49572. ></A
  49573. ><P
  49574. ><B
  49575. >Example 1. <B
  49576. CLASS="function"
  49577. >apd_dump_function_table()</B
  49578. > example</B
  49579. ></P
  49580. ><TABLE
  49581. BORDER="0"
  49582. BGCOLOR="#E0E0E0"
  49583. CELLPADDING="5"
  49584. ><TR
  49585. ><TD
  49586. ><PRE
  49587. CLASS="php"
  49588. ><?php
  49589. apd_dump_function_table();
  49590. ?></PRE
  49591. ></TD
  49592. ></TR
  49593. ></TABLE
  49594. ></DIV
  49595. ></TD
  49596. ></TR
  49597. ></TABLE
  49598. >
  49599.     </P
  49600. ></DIV
  49601. ><H1
  49602. ><A
  49603. NAME="function.apd-dump-persistent-resources"
  49604. ></A
  49605. >apd_dump_persistent_resources</H1
  49606. ><DIV
  49607. CLASS="refnamediv"
  49608. ><A
  49609. NAME="AEN8381"
  49610. ></A
  49611. ><P
  49612. >    (no version information, might be only in CVS)</P
  49613. >apd_dump_persistent_resources -- Return all persistent resources as an array</DIV
  49614. ><DIV
  49615. CLASS="refsect1"
  49616. ><A
  49617. NAME="AEN8384"
  49618. ></A
  49619. ><H2
  49620. >Description</H2
  49621. >array <B
  49622. CLASS="methodname"
  49623. >apd_dump_persistent_resources</B
  49624. > ( void )<BR
  49625. ></BR
  49626. ><P
  49627. >      Return all persistent resources as an array.
  49628.     </P
  49629. ><P
  49630. >      <TABLE
  49631. WIDTH="100%"
  49632. BORDER="0"
  49633. CELLPADDING="0"
  49634. CELLSPACING="0"
  49635. CLASS="EXAMPLE"
  49636. ><TR
  49637. ><TD
  49638. ><DIV
  49639. CLASS="example"
  49640. ><A
  49641. NAME="AEN8392"
  49642. ></A
  49643. ><P
  49644. ><B
  49645. >Example 1. <B
  49646. CLASS="function"
  49647. >apd_dump_persistent_resources()</B
  49648. > example</B
  49649. ></P
  49650. ><TABLE
  49651. BORDER="0"
  49652. BGCOLOR="#E0E0E0"
  49653. CELLPADDING="5"
  49654. ><TR
  49655. ><TD
  49656. ><PRE
  49657. CLASS="php"
  49658. ><?php
  49659. print_r(apd_dump_persistent_resources());
  49660. ?></PRE
  49661. ></TD
  49662. ></TR
  49663. ></TABLE
  49664. ></DIV
  49665. ></TD
  49666. ></TR
  49667. ></TABLE
  49668. >
  49669.     </P
  49670. ></DIV
  49671. ><H1
  49672. ><A
  49673. NAME="function.apd-dump-regular-resources"
  49674. ></A
  49675. >apd_dump_regular_resources</H1
  49676. ><DIV
  49677. CLASS="refnamediv"
  49678. ><A
  49679. NAME="AEN8397"
  49680. ></A
  49681. ><P
  49682. >    (no version information, might be only in CVS)</P
  49683. >apd_dump_regular_resources -- Return all current regular resources as an array</DIV
  49684. ><DIV
  49685. CLASS="refsect1"
  49686. ><A
  49687. NAME="AEN8400"
  49688. ></A
  49689. ><H2
  49690. >Description</H2
  49691. >array <B
  49692. CLASS="methodname"
  49693. >apd_dump_regular_resources</B
  49694. > ( void )<BR
  49695. ></BR
  49696. ><P
  49697. >      Return all current regular resources as an array.
  49698.     </P
  49699. ><P
  49700. >      <TABLE
  49701. WIDTH="100%"
  49702. BORDER="0"
  49703. CELLPADDING="0"
  49704. CELLSPACING="0"
  49705. CLASS="EXAMPLE"
  49706. ><TR
  49707. ><TD
  49708. ><DIV
  49709. CLASS="example"
  49710. ><A
  49711. NAME="AEN8408"
  49712. ></A
  49713. ><P
  49714. ><B
  49715. >Example 1. <B
  49716. CLASS="function"
  49717. >apd_dump_regular_resources()</B
  49718. > example</B
  49719. ></P
  49720. ><TABLE
  49721. BORDER="0"
  49722. BGCOLOR="#E0E0E0"
  49723. CELLPADDING="5"
  49724. ><TR
  49725. ><TD
  49726. ><PRE
  49727. CLASS="php"
  49728. ><?php
  49729. print_r(apd_dump_regular_resources());
  49730. ?></PRE
  49731. ></TD
  49732. ></TR
  49733. ></TABLE
  49734. ></DIV
  49735. ></TD
  49736. ></TR
  49737. ></TABLE
  49738. >
  49739.     </P
  49740. ></DIV
  49741. ><H1
  49742. ><A
  49743. NAME="function.apd-echo"
  49744. ></A
  49745. >apd_echo</H1
  49746. ><DIV
  49747. CLASS="refnamediv"
  49748. ><A
  49749. NAME="AEN8413"
  49750. ></A
  49751. ><P
  49752. >    (no version information, might be only in CVS)</P
  49753. >apd_echo -- Echo to the debugging socket</DIV
  49754. ><DIV
  49755. CLASS="refsect1"
  49756. ><A
  49757. NAME="AEN8416"
  49758. ></A
  49759. ><H2
  49760. >Description</H2
  49761. >void <B
  49762. CLASS="methodname"
  49763. >apd_echo</B
  49764. > ( string output)<BR
  49765. ></BR
  49766. ><P
  49767. >      Usually sent via the socket to request information about the running 
  49768.      script.
  49769.     </P
  49770. ><P
  49771. >      <TABLE
  49772. WIDTH="100%"
  49773. BORDER="0"
  49774. CELLPADDING="0"
  49775. CELLSPACING="0"
  49776. CLASS="EXAMPLE"
  49777. ><TR
  49778. ><TD
  49779. ><DIV
  49780. CLASS="example"
  49781. ><A
  49782. NAME="AEN8426"
  49783. ></A
  49784. ><P
  49785. ><B
  49786. >Example 1. <B
  49787. CLASS="function"
  49788. >apd_echo()</B
  49789. > example</B
  49790. ></P
  49791. ><TABLE
  49792. BORDER="0"
  49793. BGCOLOR="#E0E0E0"
  49794. CELLPADDING="5"
  49795. ><TR
  49796. ><TD
  49797. ><PRE
  49798. CLASS="php"
  49799. ><?php
  49800. apd_echo($i);
  49801. ?></PRE
  49802. ></TD
  49803. ></TR
  49804. ></TABLE
  49805. ></DIV
  49806. ></TD
  49807. ></TR
  49808. ></TABLE
  49809. >
  49810.     </P
  49811. ></DIV
  49812. ><H1
  49813. ><A
  49814. NAME="function.apd-get-active-symbols"
  49815. ></A
  49816. >apd_get_active_symbols</H1
  49817. ><DIV
  49818. CLASS="refnamediv"
  49819. ><A
  49820. NAME="AEN8431"
  49821. ></A
  49822. ><P
  49823. >    (no version information, might be only in CVS)</P
  49824. >apd_get_active_symbols -- Get an array of the current variables names in the local scope</DIV
  49825. ><DIV
  49826. CLASS="refsect1"
  49827. ><A
  49828. NAME="AEN8434"
  49829. ></A
  49830. ><H2
  49831. >Description</H2
  49832. >array <B
  49833. CLASS="methodname"
  49834. >apd_get_active_symbols</B
  49835. > ( )<BR
  49836. ></BR
  49837. ><P
  49838. >      Returns the names of all the variables defined in the active scope, (not 
  49839.      their values)
  49840.     </P
  49841. ><P
  49842. >      <TABLE
  49843. WIDTH="100%"
  49844. BORDER="0"
  49845. CELLPADDING="0"
  49846. CELLSPACING="0"
  49847. CLASS="EXAMPLE"
  49848. ><TR
  49849. ><TD
  49850. ><DIV
  49851. CLASS="example"
  49852. ><A
  49853. NAME="AEN8443"
  49854. ></A
  49855. ><P
  49856. ><B
  49857. >Example 1. <B
  49858. CLASS="function"
  49859. >apd_get_active_symbols()</B
  49860. > example</B
  49861. ></P
  49862. ><TABLE
  49863. BORDER="0"
  49864. BGCOLOR="#E0E0E0"
  49865. CELLPADDING="5"
  49866. ><TR
  49867. ><TD
  49868. ><PRE
  49869. CLASS="php"
  49870. ><?php
  49871. apd_echo(apd_get_active_symbols());
  49872. ?></PRE
  49873. ></TD
  49874. ></TR
  49875. ></TABLE
  49876. ></DIV
  49877. ></TD
  49878. ></TR
  49879. ></TABLE
  49880. >
  49881.     </P
  49882. ></DIV
  49883. ><H1
  49884. ><A
  49885. NAME="function.apd-set-pprof-trace"
  49886. ></A
  49887. >apd_set_pprof_trace</H1
  49888. ><DIV
  49889. CLASS="refnamediv"
  49890. ><A
  49891. NAME="AEN8448"
  49892. ></A
  49893. ><P
  49894. >    (no version information, might be only in CVS)</P
  49895. >apd_set_pprof_trace -- Starts the session debugging</DIV
  49896. ><DIV
  49897. CLASS="refsect1"
  49898. ><A
  49899. NAME="AEN8451"
  49900. ></A
  49901. ><H2
  49902. >Description</H2
  49903. >void <B
  49904. CLASS="methodname"
  49905. >apd_set_pprof_trace</B
  49906. > ( [string dump_directory])<BR
  49907. ></BR
  49908. ><P
  49909. >      Starts debugging to {dump_directory}/pprof_{process_id}, if 
  49910.      dump_directory is not set, then the apd.dumpdir setting from the 
  49911.      <TT
  49912. CLASS="filename"
  49913. >php.ini</TT
  49914. > file is used.
  49915.     </P
  49916. ><P
  49917. >      <TABLE
  49918. WIDTH="100%"
  49919. BORDER="0"
  49920. CELLPADDING="0"
  49921. CELLSPACING="0"
  49922. CLASS="EXAMPLE"
  49923. ><TR
  49924. ><TD
  49925. ><DIV
  49926. CLASS="example"
  49927. ><A
  49928. NAME="AEN8462"
  49929. ></A
  49930. ><P
  49931. ><B
  49932. >Example 1. <B
  49933. CLASS="function"
  49934. >apd_set_pprof_trace()</B
  49935. > example</B
  49936. ></P
  49937. ><TABLE
  49938. BORDER="0"
  49939. BGCOLOR="#E0E0E0"
  49940. CELLPADDING="5"
  49941. ><TR
  49942. ><TD
  49943. ><PRE
  49944. CLASS="php"
  49945. ><?php
  49946. apd_set_pprof_trace();
  49947. ?></PRE
  49948. ></TD
  49949. ></TR
  49950. ></TABLE
  49951. ></DIV
  49952. ></TD
  49953. ></TR
  49954. ></TABLE
  49955. >
  49956.     </P
  49957. ></DIV
  49958. ><H1
  49959. ><A
  49960. NAME="function.apd-set-session-trace"
  49961. ></A
  49962. >apd_set_session_trace</H1
  49963. ><DIV
  49964. CLASS="refnamediv"
  49965. ><A
  49966. NAME="AEN8467"
  49967. ></A
  49968. ><P
  49969. >    (no version information, might be only in CVS)</P
  49970. >apd_set_session_trace -- Starts the session debugging</DIV
  49971. ><DIV
  49972. CLASS="refsect1"
  49973. ><A
  49974. NAME="AEN8470"
  49975. ></A
  49976. ><H2
  49977. >Description</H2
  49978. >void <B
  49979. CLASS="methodname"
  49980. >apd_set_session_trace</B
  49981. > ( int debug_level [, string dump_directory])<BR
  49982. ></BR
  49983. ><P
  49984. >      Starts debugging to {dump_directory}/apd_dump_{process_id}, if 
  49985.      dump_directory is not set, then the apd.dumpdir setting from the 
  49986.      <TT
  49987. CLASS="filename"
  49988. >php.ini</TT
  49989. > file is used.
  49990.     </P
  49991. ><P
  49992. >      debug_level is an integer which is formed by adding together the following 
  49993.      values:
  49994.     </P
  49995. ><P
  49996. >      <TABLE
  49997. BORDER="0"
  49998. BGCOLOR="#E0E0E0"
  49999. CELLPADDING="5"
  50000. ><TR
  50001. ><TD
  50002. ><PRE
  50003. CLASS="script"
  50004. >FUNCTION_TRACE      1
  50005.         ARGS_TRACE          2
  50006.         ASSIGNMENT_TRACE    4
  50007.         STATEMENT_TRACE     8
  50008.         MEMORY_TRACE        16
  50009.         TIMING_TRACE        32
  50010.         SUMMARY_TRACE       64</PRE
  50011. ></TD
  50012. ></TR
  50013. ></TABLE
  50014. >
  50015.     </P
  50016. ><P
  50017. >      I would seriously not recommend using MEMORY_TRACE.  It is very slow and
  50018.      does not appear to be accurate (great, huh?)  also ASSIGNMENT_TRACE is not
  50019.      implemented. So, to turn on all functional traces (TIMING, FUNCTIONS, ARGS
  50020.      SUMMARY (like strace -c)) use the value 99
  50021.     </P
  50022. ><P
  50023. >      <TABLE
  50024. WIDTH="100%"
  50025. BORDER="0"
  50026. CELLPADDING="0"
  50027. CELLSPACING="0"
  50028. CLASS="EXAMPLE"
  50029. ><TR
  50030. ><TD
  50031. ><DIV
  50032. CLASS="example"
  50033. ><A
  50034. NAME="AEN8488"
  50035. ></A
  50036. ><P
  50037. ><B
  50038. >Example 1. <B
  50039. CLASS="function"
  50040. >apd_set_session_trace()</B
  50041. > example</B
  50042. ></P
  50043. ><TABLE
  50044. BORDER="0"
  50045. BGCOLOR="#E0E0E0"
  50046. CELLPADDING="5"
  50047. ><TR
  50048. ><TD
  50049. ><PRE
  50050. CLASS="php"
  50051. ><?php
  50052. apd_set_session_trace(99);
  50053. ?></PRE
  50054. ></TD
  50055. ></TR
  50056. ></TABLE
  50057. ></DIV
  50058. ></TD
  50059. ></TR
  50060. ></TABLE
  50061. >
  50062.     </P
  50063. ></DIV
  50064. ><H1
  50065. ><A
  50066. NAME="function.apd-set-session"
  50067. ></A
  50068. >apd_set_session</H1
  50069. ><DIV
  50070. CLASS="refnamediv"
  50071. ><A
  50072. NAME="AEN8493"
  50073. ></A
  50074. ><P
  50075. >    (no version information, might be only in CVS)</P
  50076. >apd_set_session -- Changes or sets the current debugging level</DIV
  50077. ><DIV
  50078. CLASS="refsect1"
  50079. ><A
  50080. NAME="AEN8496"
  50081. ></A
  50082. ><H2
  50083. >Description</H2
  50084. >void <B
  50085. CLASS="methodname"
  50086. >apd_set_session</B
  50087. > ( int debug_level)<BR
  50088. ></BR
  50089. ><P
  50090. >      This can be used to increase or decrease debugging in a different area of 
  50091.      your application,.debug_level is an integer which is formed by adding 
  50092.      together the following values:
  50093.     </P
  50094. ><P
  50095. >      <TABLE
  50096. BORDER="0"
  50097. BGCOLOR="#E0E0E0"
  50098. CELLPADDING="5"
  50099. ><TR
  50100. ><TD
  50101. ><PRE
  50102. CLASS="script"
  50103. >FUNCTION_TRACE      1
  50104.         ARGS_TRACE          2
  50105.         ASSIGNMENT_TRACE    4
  50106.         STATEMENT_TRACE     8
  50107.         MEMORY_TRACE        16
  50108.         TIMING_TRACE        32
  50109.         SUMMARY_TRACE       64</PRE
  50110. ></TD
  50111. ></TR
  50112. ></TABLE
  50113. >
  50114.     </P
  50115. ><P
  50116. >      <TABLE
  50117. WIDTH="100%"
  50118. BORDER="0"
  50119. CELLPADDING="0"
  50120. CELLSPACING="0"
  50121. CLASS="EXAMPLE"
  50122. ><TR
  50123. ><TD
  50124. ><DIV
  50125. CLASS="example"
  50126. ><A
  50127. NAME="AEN8508"
  50128. ></A
  50129. ><P
  50130. ><B
  50131. >Example 1. <B
  50132. CLASS="function"
  50133. >apd_set_session()</B
  50134. > example</B
  50135. ></P
  50136. ><TABLE
  50137. BORDER="0"
  50138. BGCOLOR="#E0E0E0"
  50139. CELLPADDING="5"
  50140. ><TR
  50141. ><TD
  50142. ><PRE
  50143. CLASS="php"
  50144. ><?php
  50145. apd_set_session(9);
  50146. ?></PRE
  50147. ></TD
  50148. ></TR
  50149. ></TABLE
  50150. ></DIV
  50151. ></TD
  50152. ></TR
  50153. ></TABLE
  50154. >
  50155.     </P
  50156. ></DIV
  50157. ><H1
  50158. ><A
  50159. NAME="function.apd-set-socket-session-trace"
  50160. ></A
  50161. >apd_set_socket_session_trace</H1
  50162. ><DIV
  50163. CLASS="refnamediv"
  50164. ><A
  50165. NAME="AEN8513"
  50166. ></A
  50167. ><P
  50168. >    (no version information, might be only in CVS)</P
  50169. >apd_set_socket_session_trace -- Starts the remote session debugging</DIV
  50170. ><DIV
  50171. CLASS="refsect1"
  50172. ><A
  50173. NAME="AEN8516"
  50174. ></A
  50175. ><H2
  50176. >Description</H2
  50177. >bool <B
  50178. CLASS="methodname"
  50179. >apd_set_socket_session_trace</B
  50180. > ( string ip_address_or_unix_socket_file, int socket_type, int port, int debug_level)<BR
  50181. ></BR
  50182. ><P
  50183. >      Connects to the tcp server (eg. tcplisten) specified IP or Unix Domain 
  50184.      socket (like a file), and sends debugging data to the socket. You can 
  50185.      use any port, but higher numbers are better as most of the lower numbers 
  50186.      may be used by other system services.
  50187.     </P
  50188. ><P
  50189. >      the socket_type can be APD_AF_UNIX (for file based sockets) or APD_AF_INET 
  50190.      (for standard tcp/ip)
  50191.     </P
  50192. ><P
  50193. >      debug_level is an integer which is formed by adding together the following 
  50194.      values:
  50195.     </P
  50196. ><P
  50197. >      <TABLE
  50198. BORDER="0"
  50199. BGCOLOR="#E0E0E0"
  50200. CELLPADDING="5"
  50201. ><TR
  50202. ><TD
  50203. ><PRE
  50204. CLASS="script"
  50205. >FUNCTION_TRACE      1
  50206.         ARGS_TRACE          2
  50207.         ASSIGNMENT_TRACE    4
  50208.         STATEMENT_TRACE     8
  50209.         MEMORY_TRACE        16
  50210.         TIMING_TRACE        32
  50211.         SUMMARY_TRACE       64</PRE
  50212. ></TD
  50213. ></TR
  50214. ></TABLE
  50215. >
  50216.     </P
  50217. ><P
  50218. >      I would seriously not recommend setting the value to 'zero' to start with, 
  50219.      and use the breakpoint methods to start debugging at a specific place in 
  50220.      the file.
  50221.     </P
  50222. ><P
  50223. >      <TABLE
  50224. WIDTH="100%"
  50225. BORDER="0"
  50226. CELLPADDING="0"
  50227. CELLSPACING="0"
  50228. CLASS="EXAMPLE"
  50229. ><TR
  50230. ><TD
  50231. ><DIV
  50232. CLASS="example"
  50233. ><A
  50234. NAME="AEN8540"
  50235. ></A
  50236. ><P
  50237. ><B
  50238. >Example 1. <B
  50239. CLASS="function"
  50240. >apd_set_socket_session_trace()</B
  50241. > example</B
  50242. ></P
  50243. ><TABLE
  50244. BORDER="0"
  50245. BGCOLOR="#E0E0E0"
  50246. CELLPADDING="5"
  50247. ><TR
  50248. ><TD
  50249. ><PRE
  50250. CLASS="php"
  50251. ><?php
  50252.   apd_set_socket_session_trace("127.0.0.1",APD_AF_INET,7112,0);
  50253. ?></PRE
  50254. ></TD
  50255. ></TR
  50256. ></TABLE
  50257. ></DIV
  50258. ></TD
  50259. ></TR
  50260. ></TABLE
  50261. >
  50262.     </P
  50263. ></DIV
  50264. ><H1
  50265. ><A
  50266. NAME="function.override-function"
  50267. ></A
  50268. >override_function</H1
  50269. ><DIV
  50270. CLASS="refnamediv"
  50271. ><A
  50272. NAME="AEN8545"
  50273. ></A
  50274. ><P
  50275. >    (no version information, might be only in CVS)</P
  50276. >override_function -- Overrides built-in functions</DIV
  50277. ><DIV
  50278. CLASS="refsect1"
  50279. ><A
  50280. NAME="AEN8548"
  50281. ></A
  50282. ><H2
  50283. >Description</H2
  50284. >bool <B
  50285. CLASS="methodname"
  50286. >override_function</B
  50287. > ( string function_name, string function_args, string function_code)<BR
  50288. ></BR
  50289. ><P
  50290. >      Syntax similar to create_function(). Overrides built-in functions
  50291.      (replaces them in the symbol table).
  50292.     </P
  50293. ><P
  50294. >      <TABLE
  50295. WIDTH="100%"
  50296. BORDER="0"
  50297. CELLPADDING="0"
  50298. CELLSPACING="0"
  50299. CLASS="EXAMPLE"
  50300. ><TR
  50301. ><TD
  50302. ><DIV
  50303. CLASS="example"
  50304. ><A
  50305. NAME="AEN8564"
  50306. ></A
  50307. ><P
  50308. ><B
  50309. >Example 1. <B
  50310. CLASS="function"
  50311. >override_function()</B
  50312. > example</B
  50313. ></P
  50314. ><TABLE
  50315. BORDER="0"
  50316. BGCOLOR="#E0E0E0"
  50317. CELLPADDING="5"
  50318. ><TR
  50319. ><TD
  50320. ><PRE
  50321. CLASS="php"
  50322. ><?php
  50323. override_function('test', '$a,$b', 'echo "DOING TEST"; return $a * $b;');
  50324. ?></PRE
  50325. ></TD
  50326. ></TR
  50327. ></TABLE
  50328. ></DIV
  50329. ></TD
  50330. ></TR
  50331. ></TABLE
  50332. >
  50333.     </P
  50334. ></DIV
  50335. ><H1
  50336. ><A
  50337. NAME="function.rename-function"
  50338. ></A
  50339. >rename_function</H1
  50340. ><DIV
  50341. CLASS="refnamediv"
  50342. ><A
  50343. NAME="AEN8569"
  50344. ></A
  50345. ><P
  50346. >    (no version information, might be only in CVS)</P
  50347. >rename_function -- Renames orig_name to new_name in the global function_table</DIV
  50348. ><DIV
  50349. CLASS="refsect1"
  50350. ><A
  50351. NAME="AEN8572"
  50352. ></A
  50353. ><H2
  50354. >Description</H2
  50355. >bool <B
  50356. CLASS="methodname"
  50357. >rename_function</B
  50358. > ( string original_name, string new_name)<BR
  50359. ></BR
  50360. ><P
  50361. >      Renames orig_name to new_name in the global function_table.  Useful
  50362.      for temporarily overriding builtin functions.
  50363.     </P
  50364. ><P
  50365. >      <TABLE
  50366. WIDTH="100%"
  50367. BORDER="0"
  50368. CELLPADDING="0"
  50369. CELLSPACING="0"
  50370. CLASS="EXAMPLE"
  50371. ><TR
  50372. ><TD
  50373. ><DIV
  50374. CLASS="example"
  50375. ><A
  50376. NAME="AEN8585"
  50377. ></A
  50378. ><P
  50379. ><B
  50380. >Example 1. <B
  50381. CLASS="function"
  50382. >rename_function()</B
  50383. > example</B
  50384. ></P
  50385. ><TABLE
  50386. BORDER="0"
  50387. BGCOLOR="#E0E0E0"
  50388. CELLPADDING="5"
  50389. ><TR
  50390. ><TD
  50391. ><PRE
  50392. CLASS="php"
  50393. ><?php
  50394. rename_function('mysql_connect', 'debug_mysql_connect' );
  50395. ?></PRE
  50396. ></TD
  50397. ></TR
  50398. ></TABLE
  50399. ></DIV
  50400. ></TD
  50401. ></TR
  50402. ></TABLE
  50403. >
  50404.     </P
  50405. ></DIV
  50406. ></DIV
  50407. ><DIV
  50408. CLASS="reference"
  50409. ><A
  50410. NAME="ref.array"
  50411. ></A
  50412. ><DIV
  50413. CLASS="TITLEPAGE"
  50414. ><H1
  50415. CLASS="title"
  50416. >III. Array Functions</H1
  50417. ><DIV
  50418. CLASS="PARTINTRO"
  50419. ><A
  50420. NAME="AEN8592"
  50421. ></A
  50422. ><DIV
  50423. CLASS="section"
  50424. ><H2
  50425. CLASS="section"
  50426. ><A
  50427. NAME="array.intro"
  50428. >Introduction</A
  50429. ></H2
  50430. ><P
  50431. >      These functions allow you to interact with and manipulate
  50432.      arrays in various ways. Arrays are essential for storing,
  50433.      managing, and operating on sets of variables.
  50434.     </P
  50435. ><P
  50436. >      Simple and multi-dimensional arrays are supported, and may be
  50437.      either user created or created by another function.
  50438.      There are specific database handling functions for populating
  50439.      arrays from database queries, and several functions return arrays.
  50440.     </P
  50441. ><P
  50442. >      Please see the <A
  50443. HREF="#language.types.array"
  50444. >Arrays</A
  50445. >
  50446.      section of the manual for a detailed explanation of how arrays are
  50447.      implemented and used in PHP.
  50448.      See also <A
  50449. HREF="#language.operators.array"
  50450. >Array operators</A
  50451. >
  50452.      for other ways how to manipulate the arrays.
  50453.     </P
  50454. ></DIV
  50455. ><DIV
  50456. CLASS="section"
  50457. ><HR><H2
  50458. CLASS="section"
  50459. ><A
  50460. NAME="array.requirements"
  50461. >Requirements</A
  50462. ></H2
  50463. ><P
  50464. >No external libraries are needed to build this extension.</P
  50465. ></DIV
  50466. ><DIV
  50467. CLASS="section"
  50468. ><HR><H2
  50469. CLASS="section"
  50470. ><A
  50471. NAME="array.installation"
  50472. >Installation</A
  50473. ></H2
  50474. ><P
  50475. >There is no installation needed to use these
  50476. functions; they are part of the PHP core.</P
  50477. ></DIV
  50478. ><DIV
  50479. CLASS="section"
  50480. ><HR><H2
  50481. CLASS="section"
  50482. ><A
  50483. NAME="array.configuration"
  50484. >Runtime Configuration</A
  50485. ></H2
  50486. ><P
  50487. >This extension has no configuration directives defined in <TT
  50488. CLASS="filename"
  50489. >php.ini</TT
  50490. >.</P
  50491. ></DIV
  50492. ><DIV
  50493. CLASS="section"
  50494. ><HR><H2
  50495. CLASS="section"
  50496. ><A
  50497. NAME="array.resources"
  50498. >Resource Types</A
  50499. ></H2
  50500. ><P
  50501. >This extension has no resource types defined.</P
  50502. ></DIV
  50503. ><DIV
  50504. CLASS="section"
  50505. ><HR><H2
  50506. CLASS="section"
  50507. ><A
  50508. NAME="array.constants"
  50509. >Predefined Constants</A
  50510. ></H2
  50511. ><P
  50512. > The constants below are always available as part of the PHP core.
  50513. </P
  50514. ><P
  50515. >  <P
  50516. ></P
  50517. ><DIV
  50518. CLASS="variablelist"
  50519. ><DL
  50520. ><DT
  50521. ><TT
  50522. CLASS="constant"
  50523. ><B
  50524. >CASE_LOWER</B
  50525. ></TT
  50526. >
  50527.     (<A
  50528. HREF="#language.types.integer"
  50529. ><B
  50530. CLASS="type"
  50531. >integer</B
  50532. ></A
  50533. >)</DT
  50534. ><DD
  50535. ><P
  50536. >      <TT
  50537. CLASS="constant"
  50538. ><B
  50539. >CASE_LOWER</B
  50540. ></TT
  50541. > is used with
  50542.      <A
  50543. HREF="#function.array-change-key-case"
  50544. ><B
  50545. CLASS="function"
  50546. >array_change_key_case()</B
  50547. ></A
  50548. > and is used to convert array
  50549.      keys to lower case. This is also the default case for
  50550.      <A
  50551. HREF="#function.array-change-key-case"
  50552. ><B
  50553. CLASS="function"
  50554. >array_change_key_case()</B
  50555. ></A
  50556. >.
  50557.     </P
  50558. ></DD
  50559. ><DT
  50560. ><TT
  50561. CLASS="constant"
  50562. ><B
  50563. >CASE_UPPER</B
  50564. ></TT
  50565. >
  50566.     (<A
  50567. HREF="#language.types.integer"
  50568. ><B
  50569. CLASS="type"
  50570. >integer</B
  50571. ></A
  50572. >)</DT
  50573. ><DD
  50574. ><P
  50575. >      <TT
  50576. CLASS="constant"
  50577. ><B
  50578. >CASE_UPPER</B
  50579. ></TT
  50580. > is used with
  50581.      <A
  50582. HREF="#function.array-change-key-case"
  50583. ><B
  50584. CLASS="function"
  50585. >array_change_key_case()</B
  50586. ></A
  50587. > and is used to convert array
  50588.      keys to upper case.
  50589.     </P
  50590. ></DD
  50591. ></DL
  50592. ></DIV
  50593. >
  50594.  </P
  50595. ><P
  50596. > Sorting order flags:
  50597.  <P
  50598. ></P
  50599. ><DIV
  50600. CLASS="variablelist"
  50601. ><DL
  50602. ><DT
  50603. ><TT
  50604. CLASS="constant"
  50605. ><B
  50606. >SORT_ASC</B
  50607. ></TT
  50608. > 
  50609.     (<A
  50610. HREF="#language.types.integer"
  50611. ><B
  50612. CLASS="type"
  50613. >integer</B
  50614. ></A
  50615. >)</DT
  50616. ><DD
  50617. ><P
  50618. >      <TT
  50619. CLASS="constant"
  50620. ><B
  50621. >SORT_ASC</B
  50622. ></TT
  50623. > is used with
  50624.      <A
  50625. HREF="#function.array-multisort"
  50626. ><B
  50627. CLASS="function"
  50628. >array_multisort()</B
  50629. ></A
  50630. > to sort in ascending order.
  50631.     </P
  50632. ></DD
  50633. ><DT
  50634. ><TT
  50635. CLASS="constant"
  50636. ><B
  50637. >SORT_DESC</B
  50638. ></TT
  50639. > 
  50640.     (<A
  50641. HREF="#language.types.integer"
  50642. ><B
  50643. CLASS="type"
  50644. >integer</B
  50645. ></A
  50646. >)</DT
  50647. ><DD
  50648. ><P
  50649. >      <TT
  50650. CLASS="constant"
  50651. ><B
  50652. >SORT_DESC</B
  50653. ></TT
  50654. > is used with
  50655.      <A
  50656. HREF="#function.array-multisort"
  50657. ><B
  50658. CLASS="function"
  50659. >array_multisort()</B
  50660. ></A
  50661. > to sort in descending order.
  50662.     </P
  50663. ></DD
  50664. ></DL
  50665. ></DIV
  50666. >
  50667.  </P
  50668. ><P
  50669. > Sorting type flags: used by various sort functions
  50670.  <P
  50671. ></P
  50672. ><DIV
  50673. CLASS="variablelist"
  50674. ><DL
  50675. ><DT
  50676. ><TT
  50677. CLASS="constant"
  50678. ><B
  50679. >SORT_REGULAR</B
  50680. ></TT
  50681. > 
  50682.     (<A
  50683. HREF="#language.types.integer"
  50684. ><B
  50685. CLASS="type"
  50686. >integer</B
  50687. ></A
  50688. >)</DT
  50689. ><DD
  50690. ><P
  50691. >      <TT
  50692. CLASS="constant"
  50693. ><B
  50694. >SORT_REGULAR</B
  50695. ></TT
  50696. > is used to compare items normally.
  50697.     </P
  50698. ></DD
  50699. ><DT
  50700. ><TT
  50701. CLASS="constant"
  50702. ><B
  50703. >SORT_NUMERIC</B
  50704. ></TT
  50705. > 
  50706.     (<A
  50707. HREF="#language.types.integer"
  50708. ><B
  50709. CLASS="type"
  50710. >integer</B
  50711. ></A
  50712. >)</DT
  50713. ><DD
  50714. ><P
  50715. >      <TT
  50716. CLASS="constant"
  50717. ><B
  50718. >SORT_NUMERIC</B
  50719. ></TT
  50720. > is used to compare items numerically.
  50721.     </P
  50722. ></DD
  50723. ><DT
  50724. ><TT
  50725. CLASS="constant"
  50726. ><B
  50727. >SORT_STRING</B
  50728. ></TT
  50729. > 
  50730.     (<A
  50731. HREF="#language.types.integer"
  50732. ><B
  50733. CLASS="type"
  50734. >integer</B
  50735. ></A
  50736. >)</DT
  50737. ><DD
  50738. ><P
  50739. >     <TT
  50740. CLASS="constant"
  50741. ><B
  50742. >SORT_STRING</B
  50743. ></TT
  50744. > is used to compare items as strings.
  50745.     </P
  50746. ></DD
  50747. ></DL
  50748. ></DIV
  50749. >
  50750.  </P
  50751. ><P
  50752. ></P
  50753. ><DIV
  50754. CLASS="variablelist"
  50755. ><DL
  50756. ><DT
  50757. ><TT
  50758. CLASS="constant"
  50759. ><B
  50760. >COUNT_NORMAL</B
  50761. ></TT
  50762. >
  50763.      (<A
  50764. HREF="#language.types.integer"
  50765. ><B
  50766. CLASS="type"
  50767. >integer</B
  50768. ></A
  50769. >)</DT
  50770. ><DD
  50771. ><P
  50772. >
  50773.     </P
  50774. ></DD
  50775. ><DT
  50776. ><TT
  50777. CLASS="constant"
  50778. ><B
  50779. >COUNT_RECURSIVE</B
  50780. ></TT
  50781. >
  50782.      (<A
  50783. HREF="#language.types.integer"
  50784. ><B
  50785. CLASS="type"
  50786. >integer</B
  50787. ></A
  50788. >)</DT
  50789. ><DD
  50790. ><P
  50791. >
  50792.     </P
  50793. ></DD
  50794. ><DT
  50795. ><TT
  50796. CLASS="constant"
  50797. ><B
  50798. >EXTR_OVERWRITE</B
  50799. ></TT
  50800. >
  50801.      (<A
  50802. HREF="#language.types.integer"
  50803. ><B
  50804. CLASS="type"
  50805. >integer</B
  50806. ></A
  50807. >)</DT
  50808. ><DD
  50809. ><P
  50810. >
  50811.     </P
  50812. ></DD
  50813. ><DT
  50814. ><TT
  50815. CLASS="constant"
  50816. ><B
  50817. >EXTR_SKIP</B
  50818. ></TT
  50819. >
  50820.      (<A
  50821. HREF="#language.types.integer"
  50822. ><B
  50823. CLASS="type"
  50824. >integer</B
  50825. ></A
  50826. >)</DT
  50827. ><DD
  50828. ><P
  50829. >
  50830.     </P
  50831. ></DD
  50832. ><DT
  50833. ><TT
  50834. CLASS="constant"
  50835. ><B
  50836. >EXTR_PREFIX_SAME</B
  50837. ></TT
  50838. >
  50839.      (<A
  50840. HREF="#language.types.integer"
  50841. ><B
  50842. CLASS="type"
  50843. >integer</B
  50844. ></A
  50845. >)</DT
  50846. ><DD
  50847. ><P
  50848. >
  50849.     </P
  50850. ></DD
  50851. ><DT
  50852. ><TT
  50853. CLASS="constant"
  50854. ><B
  50855. >EXTR_PREFIX_ALL</B
  50856. ></TT
  50857. >
  50858.      (<A
  50859. HREF="#language.types.integer"
  50860. ><B
  50861. CLASS="type"
  50862. >integer</B
  50863. ></A
  50864. >)</DT
  50865. ><DD
  50866. ><P
  50867. >
  50868.     </P
  50869. ></DD
  50870. ><DT
  50871. ><TT
  50872. CLASS="constant"
  50873. ><B
  50874. >EXTR_PREFIX_INVALID</B
  50875. ></TT
  50876. >
  50877.      (<A
  50878. HREF="#language.types.integer"
  50879. ><B
  50880. CLASS="type"
  50881. >integer</B
  50882. ></A
  50883. >)</DT
  50884. ><DD
  50885. ><P
  50886. >
  50887.     </P
  50888. ></DD
  50889. ><DT
  50890. ><TT
  50891. CLASS="constant"
  50892. ><B
  50893. >EXTR_PREFIX_IF_EXISTS</B
  50894. ></TT
  50895. >
  50896.      (<A
  50897. HREF="#language.types.integer"
  50898. ><B
  50899. CLASS="type"
  50900. >integer</B
  50901. ></A
  50902. >)</DT
  50903. ><DD
  50904. ><P
  50905. >
  50906.     </P
  50907. ></DD
  50908. ><DT
  50909. ><TT
  50910. CLASS="constant"
  50911. ><B
  50912. >EXTR_IF_EXISTS</B
  50913. ></TT
  50914. >
  50915.      (<A
  50916. HREF="#language.types.integer"
  50917. ><B
  50918. CLASS="type"
  50919. >integer</B
  50920. ></A
  50921. >)</DT
  50922. ><DD
  50923. ><P
  50924. >
  50925.     </P
  50926. ></DD
  50927. ><DT
  50928. ><TT
  50929. CLASS="constant"
  50930. ><B
  50931. >EXTR_REFS</B
  50932. ></TT
  50933. >
  50934.      (<A
  50935. HREF="#language.types.integer"
  50936. ><B
  50937. CLASS="type"
  50938. >integer</B
  50939. ></A
  50940. >)</DT
  50941. ><DD
  50942. ><P
  50943. >
  50944.     </P
  50945. ></DD
  50946. ></DL
  50947. ></DIV
  50948. ></DIV
  50949. ><DIV
  50950. CLASS="section"
  50951. ><HR><H2
  50952. CLASS="section"
  50953. ><A
  50954. NAME="array.seealso"
  50955. >See Also</A
  50956. ></H2
  50957. ><P
  50958. >      See also <A
  50959. HREF="#function.is-array"
  50960. ><B
  50961. CLASS="function"
  50962. >is_array()</B
  50963. ></A
  50964. >, <A
  50965. HREF="#function.explode"
  50966. ><B
  50967. CLASS="function"
  50968. >explode()</B
  50969. ></A
  50970. >,
  50971.      <A
  50972. HREF="#function.implode"
  50973. ><B
  50974. CLASS="function"
  50975. >implode()</B
  50976. ></A
  50977. >, <A
  50978. HREF="#function.split"
  50979. ><B
  50980. CLASS="function"
  50981. >split()</B
  50982. ></A
  50983. >,
  50984.      <A
  50985. HREF="#function.preg-split"
  50986. ><B
  50987. CLASS="function"
  50988. >preg_split()</B
  50989. ></A
  50990. >, and <A
  50991. HREF="#function.unset"
  50992. ><B
  50993. CLASS="function"
  50994. >unset()</B
  50995. ></A
  50996. >.
  50997.     </P
  50998. ></DIV
  50999. ></DIV
  51000. ><DIV
  51001. CLASS="TOC"
  51002. ><DL
  51003. ><DT
  51004. ><B
  51005. >Table of Contents</B
  51006. ></DT
  51007. ><DT
  51008. ><A
  51009. HREF="#function.array-change-key-case"
  51010. >array_change_key_case</A
  51011. > -- Returns an array with all string keys lowercased or uppercased</DT
  51012. ><DT
  51013. ><A
  51014. HREF="#function.array-chunk"
  51015. >array_chunk</A
  51016. > -- Split an array into chunks</DT
  51017. ><DT
  51018. ><A
  51019. HREF="#function.array-combine"
  51020. >array_combine</A
  51021. > -- 
  51022.      Creates an array by using one array for keys and another for its values
  51023.     </DT
  51024. ><DT
  51025. ><A
  51026. HREF="#function.array-count-values"
  51027. >array_count_values</A
  51028. > -- Counts all the values of an array</DT
  51029. ><DT
  51030. ><A
  51031. HREF="#function.array-diff-assoc"
  51032. >array_diff_assoc</A
  51033. > -- Computes the difference of arrays with additional index check</DT
  51034. ><DT
  51035. ><A
  51036. HREF="#function.array-diff-key"
  51037. >array_diff_key</A
  51038. > -- Computes the difference of arrays using keys for comparison</DT
  51039. ><DT
  51040. ><A
  51041. HREF="#function.array-diff-uassoc"
  51042. >array_diff_uassoc</A
  51043. > -- 
  51044.      Computes the difference of arrays with additional index check
  51045.      which is performed by a user supplied callback function
  51046.     </DT
  51047. ><DT
  51048. ><A
  51049. HREF="#function.array-diff-ukey"
  51050. >array_diff_ukey</A
  51051. > -- Computes the difference of arrays using a callback function on the keys for comparison</DT
  51052. ><DT
  51053. ><A
  51054. HREF="#function.array-diff"
  51055. >array_diff</A
  51056. > -- Computes the difference of arrays</DT
  51057. ><DT
  51058. ><A
  51059. HREF="#function.array-fill"
  51060. >array_fill</A
  51061. > -- Fill an array with values</DT
  51062. ><DT
  51063. ><A
  51064. HREF="#function.array-filter"
  51065. >array_filter</A
  51066. > -- 
  51067.      Filters elements of an array using a callback function
  51068.     </DT
  51069. ><DT
  51070. ><A
  51071. HREF="#function.array-flip"
  51072. >array_flip</A
  51073. > -- Exchanges all keys with their associated values in an array</DT
  51074. ><DT
  51075. ><A
  51076. HREF="#function.array-intersect-assoc"
  51077. >array_intersect_assoc</A
  51078. > -- Computes the intersection of arrays with additional index check</DT
  51079. ><DT
  51080. ><A
  51081. HREF="#function.array-intersect-key"
  51082. >array_intersect_key</A
  51083. > -- Computes the intersection of arrays using keys for comparison</DT
  51084. ><DT
  51085. ><A
  51086. HREF="#function.array-intersect-uassoc"
  51087. >array_intersect_uassoc</A
  51088. > -- Computes the intersection of arrays with additional index check, compares indexes by a callback function</DT
  51089. ><DT
  51090. ><A
  51091. HREF="#function.array-intersect-ukey"
  51092. >array_intersect_ukey</A
  51093. > -- Computes the intersection of arrays using a callback function on the keys for comparison</DT
  51094. ><DT
  51095. ><A
  51096. HREF="#function.array-intersect"
  51097. >array_intersect</A
  51098. > -- Computes the intersection of arrays</DT
  51099. ><DT
  51100. ><A
  51101. HREF="#function.array-key-exists"
  51102. >array_key_exists</A
  51103. > -- Checks if the given key or index exists in the array</DT
  51104. ><DT
  51105. ><A
  51106. HREF="#function.array-keys"
  51107. >array_keys</A
  51108. > -- Return all the keys of an array</DT
  51109. ><DT
  51110. ><A
  51111. HREF="#function.array-map"
  51112. >array_map</A
  51113. > -- 
  51114.      Applies the callback to the elements of the given arrays
  51115.     </DT
  51116. ><DT
  51117. ><A
  51118. HREF="#function.array-merge-recursive"
  51119. >array_merge_recursive</A
  51120. > -- Merge two or more arrays recursively</DT
  51121. ><DT
  51122. ><A
  51123. HREF="#function.array-merge"
  51124. >array_merge</A
  51125. > -- Merge one or more arrays</DT
  51126. ><DT
  51127. ><A
  51128. HREF="#function.array-multisort"
  51129. >array_multisort</A
  51130. > -- Sort multiple or multi-dimensional arrays</DT
  51131. ><DT
  51132. ><A
  51133. HREF="#function.array-pad"
  51134. >array_pad</A
  51135. > -- 
  51136.      Pad array to the specified length with a value
  51137.     </DT
  51138. ><DT
  51139. ><A
  51140. HREF="#function.array-pop"
  51141. >array_pop</A
  51142. > -- Pop the element off the end of array</DT
  51143. ><DT
  51144. ><A
  51145. HREF="#function.array-push"
  51146. >array_push</A
  51147. > -- 
  51148.      Push one or more elements onto the end of array
  51149.     </DT
  51150. ><DT
  51151. ><A
  51152. HREF="#function.array-rand"
  51153. >array_rand</A
  51154. > -- 
  51155.      Pick one or more random entries out of an array
  51156.     </DT
  51157. ><DT
  51158. ><A
  51159. HREF="#function.array-reduce"
  51160. >array_reduce</A
  51161. > -- 
  51162.      Iteratively reduce the array to a single value using a callback
  51163.      function
  51164.     </DT
  51165. ><DT
  51166. ><A
  51167. HREF="#function.array-reverse"
  51168. >array_reverse</A
  51169. > -- 
  51170.      Return an array with elements in reverse order
  51171.     </DT
  51172. ><DT
  51173. ><A
  51174. HREF="#function.array-search"
  51175. >array_search</A
  51176. > -- 
  51177.      Searches the array for a given value and returns the
  51178.      corresponding key if successful
  51179.     </DT
  51180. ><DT
  51181. ><A
  51182. HREF="#function.array-shift"
  51183. >array_shift</A
  51184. > -- 
  51185.      Shift an element off the beginning of array
  51186.     </DT
  51187. ><DT
  51188. ><A
  51189. HREF="#function.array-slice"
  51190. >array_slice</A
  51191. > -- Extract a slice of the array</DT
  51192. ><DT
  51193. ><A
  51194. HREF="#function.array-splice"
  51195. >array_splice</A
  51196. > -- 
  51197.      Remove a portion of the array and replace it with something
  51198.      else
  51199.     </DT
  51200. ><DT
  51201. ><A
  51202. HREF="#function.array-sum"
  51203. >array_sum</A
  51204. > -- 
  51205.      Calculate the sum of values in an array
  51206.     </DT
  51207. ><DT
  51208. ><A
  51209. HREF="#function.array-udiff-assoc"
  51210. >array_udiff_assoc</A
  51211. > -- Computes the difference of arrays with additional index check, compares data by a callback function</DT
  51212. ><DT
  51213. ><A
  51214. HREF="#function.array-udiff-uassoc"
  51215. >array_udiff_uassoc</A
  51216. > -- Computes the difference of arrays with additional index check, compares data and indexes by a callback function</DT
  51217. ><DT
  51218. ><A
  51219. HREF="#function.array-udiff"
  51220. >array_udiff</A
  51221. > -- Computes the difference of arrays by using a callback function for data comparison</DT
  51222. ><DT
  51223. ><A
  51224. HREF="#function.array-uintersect-assoc"
  51225. >array_uintersect_assoc</A
  51226. > -- Computes the intersection of arrays with additional index check, compares data by a callback function</DT
  51227. ><DT
  51228. ><A
  51229. HREF="#function.array-uintersect-uassoc"
  51230. >array_uintersect_uassoc</A
  51231. > -- Computes the intersection of arrays with additional index check, compares data and indexes by a callback functions</DT
  51232. ><DT
  51233. ><A
  51234. HREF="#function.array-uintersect"
  51235. >array_uintersect</A
  51236. > -- Computes the intersection of arrays, compares data by a callback function</DT
  51237. ><DT
  51238. ><A
  51239. HREF="#function.array-unique"
  51240. >array_unique</A
  51241. > -- Removes duplicate values from an array</DT
  51242. ><DT
  51243. ><A
  51244. HREF="#function.array-unshift"
  51245. >array_unshift</A
  51246. > -- 
  51247.      Prepend one or more elements to the beginning of an array
  51248.     </DT
  51249. ><DT
  51250. ><A
  51251. HREF="#function.array-values"
  51252. >array_values</A
  51253. > -- Return all the values of an array</DT
  51254. ><DT
  51255. ><A
  51256. HREF="#function.array-walk-recursive"
  51257. >array_walk_recursive</A
  51258. > -- 
  51259.    Apply a user function recursively to every member of an array
  51260.   </DT
  51261. ><DT
  51262. ><A
  51263. HREF="#function.array-walk"
  51264. >array_walk</A
  51265. > -- 
  51266.      Apply a user function to every member of an array
  51267.     </DT
  51268. ><DT
  51269. ><A
  51270. HREF="#function.array"
  51271. >array</A
  51272. > -- 
  51273.      Create an array
  51274.     </DT
  51275. ><DT
  51276. ><A
  51277. HREF="#function.arsort"
  51278. >arsort</A
  51279. > -- 
  51280.      Sort an array in reverse order and maintain index association
  51281.     </DT
  51282. ><DT
  51283. ><A
  51284. HREF="#function.asort"
  51285. >asort</A
  51286. > -- Sort an array and maintain index association</DT
  51287. ><DT
  51288. ><A
  51289. HREF="#function.compact"
  51290. >compact</A
  51291. > -- 
  51292.      Create array containing variables and their values
  51293.     </DT
  51294. ><DT
  51295. ><A
  51296. HREF="#function.count"
  51297. >count</A
  51298. > -- Count elements in an array, or properties in an object</DT
  51299. ><DT
  51300. ><A
  51301. HREF="#function.current"
  51302. >current</A
  51303. > -- Return the current element in an array</DT
  51304. ><DT
  51305. ><A
  51306. HREF="#function.each"
  51307. >each</A
  51308. > -- 
  51309.      Return the current key and value pair from an array and advance
  51310.      the array cursor
  51311.     </DT
  51312. ><DT
  51313. ><A
  51314. HREF="#function.end"
  51315. >end</A
  51316. > -- 
  51317.      Set the internal pointer of an array to its last element
  51318.     </DT
  51319. ><DT
  51320. ><A
  51321. HREF="#function.extract"
  51322. >extract</A
  51323. > -- 
  51324.      Import variables into the current symbol table from an array
  51325.     </DT
  51326. ><DT
  51327. ><A
  51328. HREF="#function.in-array"
  51329. >in_array</A
  51330. > -- Checks if a value exists in an array</DT
  51331. ><DT
  51332. ><A
  51333. HREF="#function.key"
  51334. >key</A
  51335. > -- Fetch a key from an associative array</DT
  51336. ><DT
  51337. ><A
  51338. HREF="#function.krsort"
  51339. >krsort</A
  51340. > -- Sort an array by key in reverse order</DT
  51341. ><DT
  51342. ><A
  51343. HREF="#function.ksort"
  51344. >ksort</A
  51345. > -- Sort an array by key</DT
  51346. ><DT
  51347. ><A
  51348. HREF="#function.list"
  51349. >list</A
  51350. > -- 
  51351.      Assign variables as if they were an array
  51352.     </DT
  51353. ><DT
  51354. ><A
  51355. HREF="#function.natcasesort"
  51356. >natcasesort</A
  51357. > -- 
  51358.      Sort an array using a case insensitive "natural order" algorithm
  51359.     </DT
  51360. ><DT
  51361. ><A
  51362. HREF="#function.natsort"
  51363. >natsort</A
  51364. > -- 
  51365.      Sort an array using a "natural order" algorithm
  51366.     </DT
  51367. ><DT
  51368. ><A
  51369. HREF="#function.next"
  51370. >next</A
  51371. > -- 
  51372.      Advance the internal array pointer of an array
  51373.     </DT
  51374. ><DT
  51375. ><A
  51376. HREF="#function.pos"
  51377. >pos</A
  51378. > -- Alias of <A
  51379. HREF="#function.current"
  51380. ><B
  51381. CLASS="function"
  51382. >current()</B
  51383. ></A
  51384. ></DT
  51385. ><DT
  51386. ><A
  51387. HREF="#function.prev"
  51388. >prev</A
  51389. > -- Rewind the internal array pointer</DT
  51390. ><DT
  51391. ><A
  51392. HREF="#function.range"
  51393. >range</A
  51394. > -- 
  51395.      Create an array containing a range of elements
  51396.     </DT
  51397. ><DT
  51398. ><A
  51399. HREF="#function.reset"
  51400. >reset</A
  51401. > -- 
  51402.      Set the internal pointer of an array to its first element
  51403.     </DT
  51404. ><DT
  51405. ><A
  51406. HREF="#function.rsort"
  51407. >rsort</A
  51408. > -- Sort an array in reverse order</DT
  51409. ><DT
  51410. ><A
  51411. HREF="#function.shuffle"
  51412. >shuffle</A
  51413. > -- Shuffle an array</DT
  51414. ><DT
  51415. ><A
  51416. HREF="#function.sizeof"
  51417. >sizeof</A
  51418. > -- Alias of <A
  51419. HREF="#function.count"
  51420. ><B
  51421. CLASS="function"
  51422. >count()</B
  51423. ></A
  51424. ></DT
  51425. ><DT
  51426. ><A
  51427. HREF="#function.sort"
  51428. >sort</A
  51429. > -- Sort an array</DT
  51430. ><DT
  51431. ><A
  51432. HREF="#function.uasort"
  51433. >uasort</A
  51434. > -- 
  51435.      Sort an array with a user-defined comparison function and
  51436.      maintain index association
  51437.     </DT
  51438. ><DT
  51439. ><A
  51440. HREF="#function.uksort"
  51441. >uksort</A
  51442. > -- 
  51443.      Sort an array by keys using a user-defined comparison function
  51444.     </DT
  51445. ><DT
  51446. ><A
  51447. HREF="#function.usort"
  51448. >usort</A
  51449. > -- 
  51450.      Sort an array by values using a user-defined comparison function
  51451.     </DT
  51452. ></DL
  51453. ></DIV
  51454. ></DIV
  51455. ><H1
  51456. ><A
  51457. NAME="function.array-change-key-case"
  51458. ></A
  51459. >array_change_key_case</H1
  51460. ><DIV
  51461. CLASS="refnamediv"
  51462. ><A
  51463. NAME="AEN8747"
  51464. ></A
  51465. ><P
  51466. >    (PHP 4 >= 4.2.0, PHP 5)</P
  51467. >array_change_key_case -- Returns an array with all string keys lowercased or uppercased</DIV
  51468. ><DIV
  51469. CLASS="refsect1"
  51470. ><A
  51471. NAME="AEN8750"
  51472. ></A
  51473. ><H2
  51474. >Description</H2
  51475. >array <B
  51476. CLASS="methodname"
  51477. >array_change_key_case</B
  51478. > ( array input [, int case])<BR
  51479. ></BR
  51480. ><P
  51481. >      <B
  51482. CLASS="function"
  51483. >array_change_key_case()</B
  51484. > changes the
  51485.      keys in the <VAR
  51486. CLASS="parameter"
  51487. >input</VAR
  51488. > array to
  51489.      be all lowercase or uppercase. The change depends
  51490.      on the last optional <VAR
  51491. CLASS="parameter"
  51492. >case</VAR
  51493. >
  51494.      parameter. You can pass two constants there,
  51495.      <TT
  51496. CLASS="constant"
  51497. ><B
  51498. >CASE_UPPER</B
  51499. ></TT
  51500. > and
  51501.      <TT
  51502. CLASS="constant"
  51503. ><B
  51504. >CASE_LOWER</B
  51505. ></TT
  51506. >. The default is
  51507.      <TT
  51508. CLASS="constant"
  51509. ><B
  51510. >CASE_LOWER</B
  51511. ></TT
  51512. >. The function will leave
  51513.      number indices as is.
  51514.     </P
  51515. ><TABLE
  51516. WIDTH="100%"
  51517. BORDER="0"
  51518. CELLPADDING="0"
  51519. CELLSPACING="0"
  51520. CLASS="EXAMPLE"
  51521. ><TR
  51522. ><TD
  51523. ><DIV
  51524. CLASS="example"
  51525. ><A
  51526. NAME="AEN8768"
  51527. ></A
  51528. ><P
  51529. ><B
  51530. >Example 1. <B
  51531. CLASS="function"
  51532. >array_change_key_case()</B
  51533. > example</B
  51534. ></P
  51535. ><TABLE
  51536. BORDER="0"
  51537. BGCOLOR="#E0E0E0"
  51538. CELLPADDING="5"
  51539. ><TR
  51540. ><TD
  51541. ><PRE
  51542. CLASS="php"
  51543. ><?php
  51544. $input_array = array("FirSt" => 1, "SecOnd" => 4);
  51545. print_r(array_change_key_case($input_array, CASE_UPPER));
  51546. ?></PRE
  51547. ></TD
  51548. ></TR
  51549. ></TABLE
  51550. ><P
  51551. >The above example will output:</P
  51552. ><TABLE
  51553. BORDER="0"
  51554. BGCOLOR="#E0E0E0"
  51555. CELLPADDING="5"
  51556. ><TR
  51557. ><TD
  51558. ><PRE
  51559. CLASS="screen"
  51560. >Array
  51561. (
  51562.     [FIRST] => 1
  51563.     [SECOND] => 4
  51564. )</PRE
  51565. ></TD
  51566. ></TR
  51567. ></TABLE
  51568. ></DIV
  51569. ></TD
  51570. ></TR
  51571. ></TABLE
  51572. ><P
  51573. >      If an array has indices that will be the same once run through this
  51574.      function (e.g. "keY" and "kEY"), the value that is later in the array
  51575.      will override other indices.
  51576.     </P
  51577. ></DIV
  51578. ><H1
  51579. ><A
  51580. NAME="function.array-chunk"
  51581. ></A
  51582. >array_chunk</H1
  51583. ><DIV
  51584. CLASS="refnamediv"
  51585. ><A
  51586. NAME="AEN8776"
  51587. ></A
  51588. ><P
  51589. >    (PHP 4 >= 4.2.0, PHP 5)</P
  51590. >array_chunk -- Split an array into chunks</DIV
  51591. ><DIV
  51592. CLASS="refsect1"
  51593. ><A
  51594. NAME="AEN8779"
  51595. ></A
  51596. ><H2
  51597. >Description</H2
  51598. >array <B
  51599. CLASS="methodname"
  51600. >array_chunk</B
  51601. > ( array input, int size [, bool preserve_keys])<BR
  51602. ></BR
  51603. ><P
  51604. >      <B
  51605. CLASS="function"
  51606. >array_chunk()</B
  51607. > splits the array into
  51608.      several arrays with <VAR
  51609. CLASS="parameter"
  51610. >size</VAR
  51611. > values
  51612.      in them. You may also have an array with less values
  51613.      at the end. You get the arrays as members of a
  51614.      multidimensional array indexed with numbers starting
  51615.      from zero.
  51616.     </P
  51617. ><P
  51618. >      By setting the optional <VAR
  51619. CLASS="parameter"
  51620. >preserve_keys</VAR
  51621. >
  51622.      parameter to <TT
  51623. CLASS="constant"
  51624. ><B
  51625. >TRUE</B
  51626. ></TT
  51627. >, you can force PHP to preserve the original
  51628.      keys from the input array. If you specify <TT
  51629. CLASS="constant"
  51630. ><B
  51631. >FALSE</B
  51632. ></TT
  51633. > new number
  51634.      indices will be used in each resulting array with
  51635.      indices starting from zero. The default is <TT
  51636. CLASS="constant"
  51637. ><B
  51638. >FALSE</B
  51639. ></TT
  51640. >.
  51641.     </P
  51642. ><TABLE
  51643. WIDTH="100%"
  51644. BORDER="0"
  51645. CELLPADDING="0"
  51646. CELLSPACING="0"
  51647. CLASS="EXAMPLE"
  51648. ><TR
  51649. ><TD
  51650. ><DIV
  51651. CLASS="example"
  51652. ><A
  51653. NAME="AEN8801"
  51654. ></A
  51655. ><P
  51656. ><B
  51657. >Example 1. <B
  51658. CLASS="function"
  51659. >array_chunk()</B
  51660. > example</B
  51661. ></P
  51662. ><TABLE
  51663. BORDER="0"
  51664. BGCOLOR="#E0E0E0"
  51665. CELLPADDING="5"
  51666. ><TR
  51667. ><TD
  51668. ><PRE
  51669. CLASS="php"
  51670. ><?php
  51671. $input_array = array('a', 'b', 'c', 'd', 'e');
  51672. print_r(array_chunk($input_array, 2));
  51673. print_r(array_chunk($input_array, 2, true));
  51674. ?></PRE
  51675. ></TD
  51676. ></TR
  51677. ></TABLE
  51678. ><P
  51679. >The above example will output:</P
  51680. ><TABLE
  51681. BORDER="0"
  51682. BGCOLOR="#E0E0E0"
  51683. CELLPADDING="5"
  51684. ><TR
  51685. ><TD
  51686. ><PRE
  51687. CLASS="screen"
  51688. >Array
  51689. (
  51690.     [0] => Array
  51691.         (
  51692.             [0] => a
  51693.             [1] => b
  51694.         )
  51695.  
  51696.     [1] => Array
  51697.         (
  51698.             [0] => c
  51699.             [1] => d
  51700.         )
  51701.  
  51702.     [2] => Array
  51703.         (
  51704.             [0] => e
  51705.         )
  51706.  
  51707. )
  51708. Array
  51709. (
  51710.     [0] => Array
  51711.         (
  51712.             [0] => a
  51713.             [1] => b
  51714.         )
  51715.  
  51716.     [1] => Array
  51717.         (
  51718.             [2] => c
  51719.             [3] => d
  51720.         )
  51721.  
  51722.     [2] => Array
  51723.         (
  51724.             [4] => e
  51725.         )
  51726.  
  51727. )</PRE
  51728. ></TD
  51729. ></TR
  51730. ></TABLE
  51731. ></DIV
  51732. ></TD
  51733. ></TR
  51734. ></TABLE
  51735. ></DIV
  51736. ><H1
  51737. ><A
  51738. NAME="function.array-combine"
  51739. ></A
  51740. >array_combine</H1
  51741. ><DIV
  51742. CLASS="refnamediv"
  51743. ><A
  51744. NAME="AEN8808"
  51745. ></A
  51746. ><P
  51747. >    (PHP 5)</P
  51748. >array_combine -- 
  51749.      Creates an array by using one array for keys and another for its values
  51750.     </DIV
  51751. ><DIV
  51752. CLASS="refsect1"
  51753. ><A
  51754. NAME="AEN8811"
  51755. ></A
  51756. ><H2
  51757. >Description</H2
  51758. >array <B
  51759. CLASS="methodname"
  51760. >array_combine</B
  51761. > ( array keys, array values)<BR
  51762. ></BR
  51763. ><P
  51764. >      Returns an <A
  51765. HREF="#language.types.array"
  51766. ><B
  51767. CLASS="type"
  51768. >array</B
  51769. ></A
  51770. > by using the values from the
  51771.      <VAR
  51772. CLASS="parameter"
  51773. >keys</VAR
  51774. > array as keys and the values from the
  51775.      <VAR
  51776. CLASS="parameter"
  51777. >values</VAR
  51778. > array as the corresponding values.
  51779.     </P
  51780. ><P
  51781. >      Returns <TT
  51782. CLASS="constant"
  51783. ><B
  51784. >FALSE</B
  51785. ></TT
  51786. > if the number of elements for each array isn't equal or
  51787.      if the arrays are empty.
  51788.     </P
  51789. ><P
  51790. >      <TABLE
  51791. WIDTH="100%"
  51792. BORDER="0"
  51793. CELLPADDING="0"
  51794. CELLSPACING="0"
  51795. CLASS="EXAMPLE"
  51796. ><TR
  51797. ><TD
  51798. ><DIV
  51799. CLASS="example"
  51800. ><A
  51801. NAME="AEN8829"
  51802. ></A
  51803. ><P
  51804. ><B
  51805. >Example 1. A simple <B
  51806. CLASS="function"
  51807. >array_combine()</B
  51808. > example</B
  51809. ></P
  51810. ><TABLE
  51811. BORDER="0"
  51812. BGCOLOR="#E0E0E0"
  51813. CELLPADDING="5"
  51814. ><TR
  51815. ><TD
  51816. ><PRE
  51817. CLASS="php"
  51818. ><?php
  51819. $a = array('green', 'red', 'yellow');
  51820. $b = array('avocado', 'apple', 'banana');
  51821. $c = array_combine($a, $b);
  51822.  
  51823. print_r($c);
  51824. ?></PRE
  51825. ></TD
  51826. ></TR
  51827. ></TABLE
  51828. ><P
  51829. >The above example will output:</P
  51830. ><TABLE
  51831. BORDER="0"
  51832. BGCOLOR="#E0E0E0"
  51833. CELLPADDING="5"
  51834. ><TR
  51835. ><TD
  51836. ><PRE
  51837. CLASS="screen"
  51838. >Array
  51839. (
  51840.     [green]  => avocado
  51841.     [red]    => apple
  51842.     [yellow] => banana
  51843. )</PRE
  51844. ></TD
  51845. ></TR
  51846. ></TABLE
  51847. ></DIV
  51848. ></TD
  51849. ></TR
  51850. ></TABLE
  51851. >
  51852.     </P
  51853. ><P
  51854. >      See also <A
  51855. HREF="#function.array-merge"
  51856. ><B
  51857. CLASS="function"
  51858. >array_merge()</B
  51859. ></A
  51860. >,
  51861.      <A
  51862. HREF="#function.array-walk"
  51863. ><B
  51864. CLASS="function"
  51865. >array_walk()</B
  51866. ></A
  51867. >, and
  51868.      <A
  51869. HREF="#function.array-values"
  51870. ><B
  51871. CLASS="function"
  51872. >array_values()</B
  51873. ></A
  51874. >.
  51875.     </P
  51876. ></DIV
  51877. ><H1
  51878. ><A
  51879. NAME="function.array-count-values"
  51880. ></A
  51881. >array_count_values</H1
  51882. ><DIV
  51883. CLASS="refnamediv"
  51884. ><A
  51885. NAME="AEN8840"
  51886. ></A
  51887. ><P
  51888. >    (PHP 4 , PHP 5)</P
  51889. >array_count_values -- Counts all the values of an array</DIV
  51890. ><DIV
  51891. CLASS="refsect1"
  51892. ><A
  51893. NAME="AEN8843"
  51894. ></A
  51895. ><H2
  51896. >Description</H2
  51897. >array <B
  51898. CLASS="methodname"
  51899. >array_count_values</B
  51900. > ( array input)<BR
  51901. ></BR
  51902. ><P
  51903. >      <B
  51904. CLASS="function"
  51905. >array_count_values()</B
  51906. > returns an array using
  51907.      the values of the <VAR
  51908. CLASS="parameter"
  51909. >input</VAR
  51910. > array as keys and
  51911.      their frequency in <VAR
  51912. CLASS="parameter"
  51913. >input</VAR
  51914. > as values.
  51915.     </P
  51916. ><P
  51917. >      <TABLE
  51918. WIDTH="100%"
  51919. BORDER="0"
  51920. CELLPADDING="0"
  51921. CELLSPACING="0"
  51922. CLASS="EXAMPLE"
  51923. ><TR
  51924. ><TD
  51925. ><DIV
  51926. CLASS="example"
  51927. ><A
  51928. NAME="AEN8856"
  51929. ></A
  51930. ><P
  51931. ><B
  51932. >Example 1. <B
  51933. CLASS="function"
  51934. >array_count_values()</B
  51935. > example</B
  51936. ></P
  51937. ><TABLE
  51938. BORDER="0"
  51939. BGCOLOR="#E0E0E0"
  51940. CELLPADDING="5"
  51941. ><TR
  51942. ><TD
  51943. ><PRE
  51944. CLASS="php"
  51945. ><?php
  51946. $array = array(1, "hello", 1, "world", "hello");
  51947. print_r(array_count_values($array));
  51948. ?></PRE
  51949. ></TD
  51950. ></TR
  51951. ></TABLE
  51952. ><P
  51953. >The above example will output:</P
  51954. ><TABLE
  51955. BORDER="0"
  51956. BGCOLOR="#E0E0E0"
  51957. CELLPADDING="5"
  51958. ><TR
  51959. ><TD
  51960. ><PRE
  51961. CLASS="screen"
  51962. >Array
  51963. (
  51964.     [1] => 2
  51965.     [hello] => 2
  51966.     [world] => 1
  51967. )</PRE
  51968. ></TD
  51969. ></TR
  51970. ></TABLE
  51971. ></DIV
  51972. ></TD
  51973. ></TR
  51974. ></TABLE
  51975. >
  51976.     </P
  51977. ><P
  51978. >      See also <A
  51979. HREF="#function.count"
  51980. ><B
  51981. CLASS="function"
  51982. >count()</B
  51983. ></A
  51984. >,
  51985.      <A
  51986. HREF="#function.array-unique"
  51987. ><B
  51988. CLASS="function"
  51989. >array_unique()</B
  51990. ></A
  51991. >,
  51992.      <A
  51993. HREF="#function.array-values"
  51994. ><B
  51995. CLASS="function"
  51996. >array_values()</B
  51997. ></A
  51998. >, and
  51999.      <A
  52000. HREF="#function.count-chars"
  52001. ><B
  52002. CLASS="function"
  52003. >count_chars()</B
  52004. ></A
  52005. >.
  52006.     </P
  52007. ></DIV
  52008. ><H1
  52009. ><A
  52010. NAME="function.array-diff-assoc"
  52011. ></A
  52012. >array_diff_assoc</H1
  52013. ><DIV
  52014. CLASS="refnamediv"
  52015. ><A
  52016. NAME="AEN8868"
  52017. ></A
  52018. ><P
  52019. >    (PHP 4 >= 4.3.0, PHP 5)</P
  52020. >array_diff_assoc -- Computes the difference of arrays with additional index check</DIV
  52021. ><DIV
  52022. CLASS="refsect1"
  52023. ><A
  52024. NAME="AEN8871"
  52025. ></A
  52026. ><H2
  52027. >Description</H2
  52028. >array <B
  52029. CLASS="methodname"
  52030. >array_diff_assoc</B
  52031. > ( array array1, array array2 [, array ...])<BR
  52032. ></BR
  52033. ><P
  52034. >      <B
  52035. CLASS="function"
  52036. >array_diff_assoc()</B
  52037. > returns an <A
  52038. HREF="#language.types.array"
  52039. ><B
  52040. CLASS="type"
  52041. >array</B
  52042. ></A
  52043. >
  52044.      containing all the values from <VAR
  52045. CLASS="parameter"
  52046. >array1</VAR
  52047. >
  52048.      that are not present in any of the other arguments.
  52049.      Note that the keys are used in the comparison unlike
  52050.      <A
  52051. HREF="#function.array-diff"
  52052. ><B
  52053. CLASS="function"
  52054. >array_diff()</B
  52055. ></A
  52056. >.
  52057.     </P
  52058. ><P
  52059. >      <TABLE
  52060. WIDTH="100%"
  52061. BORDER="0"
  52062. CELLPADDING="0"
  52063. CELLSPACING="0"
  52064. CLASS="EXAMPLE"
  52065. ><TR
  52066. ><TD
  52067. ><DIV
  52068. CLASS="example"
  52069. ><A
  52070. NAME="AEN8891"
  52071. ></A
  52072. ><P
  52073. ><B
  52074. >Example 1. <B
  52075. CLASS="function"
  52076. >array_diff_assoc()</B
  52077. > example</B
  52078. ></P
  52079. ><TABLE
  52080. BORDER="0"
  52081. BGCOLOR="#E0E0E0"
  52082. CELLPADDING="5"
  52083. ><TR
  52084. ><TD
  52085. ><PRE
  52086. CLASS="php"
  52087. ><?php
  52088. $array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
  52089. $array2 = array("a" => "green", "yellow", "red");
  52090. $result = array_diff_assoc($array1, $array2);
  52091. print_r($result);
  52092. ?></PRE
  52093. ></TD
  52094. ></TR
  52095. ></TABLE
  52096. ><P
  52097. >The above example will output:</P
  52098. ><TABLE
  52099. BORDER="0"
  52100. BGCOLOR="#E0E0E0"
  52101. CELLPADDING="5"
  52102. ><TR
  52103. ><TD
  52104. ><PRE
  52105. CLASS="screen"
  52106. >Array
  52107. (
  52108.     [b] => brown
  52109.     [c] => blue
  52110.     [0] => red
  52111. )</PRE
  52112. ></TD
  52113. ></TR
  52114. ></TABLE
  52115. ></DIV
  52116. ></TD
  52117. ></TR
  52118. ></TABLE
  52119. >
  52120.     </P
  52121. ><P
  52122. >      In our example above you see the <VAR
  52123. CLASS="literal"
  52124. >"a" => "green"</VAR
  52125. >
  52126.      pair is present in both arrays and thus it is not in the ouput from the
  52127.      function. Unlike this, the pair <VAR
  52128. CLASS="literal"
  52129. >0 => "red"</VAR
  52130. > 
  52131.      is in the ouput because in the second argument <VAR
  52132. CLASS="literal"
  52133. >"red"</VAR
  52134. >
  52135.      has key which is <VAR
  52136. CLASS="literal"
  52137. >1</VAR
  52138. >. 
  52139.     </P
  52140. ><P
  52141. >      Two values from <SPAN
  52142. CLASS="emphasis"
  52143. ><I
  52144. CLASS="emphasis"
  52145. >key => value</I
  52146. ></SPAN
  52147. > pairs are
  52148.      considered equal only if <VAR
  52149. CLASS="literal"
  52150. >(string) $elem1 === (string)
  52151.      $elem2 </VAR
  52152. >. In other words a strict check takes place so 
  52153.      the string representations must be the same.
  52154.      
  52155.     </P
  52156. ><DIV
  52157. CLASS="note"
  52158. ><BLOCKQUOTE
  52159. CLASS="note"
  52160. ><P
  52161. ><B
  52162. >Note: </B
  52163. >
  52164.       Please note that this function only checks one dimension of a n-dimensional
  52165.       array. Of course you can check deeper dimensions by using, for example, 
  52166.       <VAR
  52167. CLASS="literal"
  52168. >array_diff_assoc($array1[0], $array2[0]);</VAR
  52169. >.
  52170.      </P
  52171. ></BLOCKQUOTE
  52172. ></DIV
  52173. ><P
  52174. >      See also <A
  52175. HREF="#function.array-diff"
  52176. ><B
  52177. CLASS="function"
  52178. >array_diff()</B
  52179. ></A
  52180. >,
  52181.      <A
  52182. HREF="#function.array-intersect"
  52183. ><B
  52184. CLASS="function"
  52185. >array_intersect()</B
  52186. ></A
  52187. >,
  52188.      and <A
  52189. HREF="#function.array-intersect-assoc"
  52190. ><B
  52191. CLASS="function"
  52192. >array_intersect_assoc()</B
  52193. ></A
  52194. >.
  52195.     </P
  52196. ></DIV
  52197. ><H1
  52198. ><A
  52199. NAME="function.array-diff-key"
  52200. ></A
  52201. >array_diff_key</H1
  52202. ><DIV
  52203. CLASS="refnamediv"
  52204. ><A
  52205. NAME="AEN8913"
  52206. ></A
  52207. ><P
  52208. >    (no version information, might be only in CVS)</P
  52209. >array_diff_key -- Computes the difference of arrays using keys for comparison</DIV
  52210. ><DIV
  52211. CLASS="refsect1"
  52212. ><A
  52213. NAME="AEN8916"
  52214. ></A
  52215. ><H2
  52216. >Description</H2
  52217. >array <B
  52218. CLASS="methodname"
  52219. >array_diff_key</B
  52220. > ( array array1, array array2 [, array ...])<BR
  52221. ></BR
  52222. ><P
  52223. >      <B
  52224. CLASS="function"
  52225. >array_diff_key()</B
  52226. > returns an array
  52227.      containing all the values of <VAR
  52228. CLASS="parameter"
  52229. >array1</VAR
  52230. >
  52231.      that have keys that are not present in any of the other arguments.
  52232.      Note that the associativity is preserved. This function is like
  52233.      <A
  52234. HREF="#function.array-diff"
  52235. ><B
  52236. CLASS="function"
  52237. >array_diff()</B
  52238. ></A
  52239. > except the comparison is done on the
  52240.      keys instead of the values.
  52241.     </P
  52242. ><P
  52243. >      <TABLE
  52244. WIDTH="100%"
  52245. BORDER="0"
  52246. CELLPADDING="0"
  52247. CELLSPACING="0"
  52248. CLASS="EXAMPLE"
  52249. ><TR
  52250. ><TD
  52251. ><DIV
  52252. CLASS="example"
  52253. ><A
  52254. NAME="AEN8935"
  52255. ></A
  52256. ><P
  52257. ><B
  52258. >Example 1. <B
  52259. CLASS="function"
  52260. >array_diff_key()</B
  52261. > example</B
  52262. ></P
  52263. ><TABLE
  52264. BORDER="0"
  52265. BGCOLOR="#E0E0E0"
  52266. CELLPADDING="5"
  52267. ><TR
  52268. ><TD
  52269. ><PRE
  52270. CLASS="php"
  52271. ><?php
  52272. $array1 = array('blue'  => 1, 'red'  => 2, 'green'  => 3, 'purple' => 4);
  52273. $array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan'   => 8);
  52274.  
  52275. var_dump(array_diff_key($array1, $array2));
  52276. ?></PRE
  52277. ></TD
  52278. ></TR
  52279. ></TABLE
  52280. ><P
  52281. >The above example will output:</P
  52282. ><TABLE
  52283. BORDER="0"
  52284. BGCOLOR="#E0E0E0"
  52285. CELLPADDING="5"
  52286. ><TR
  52287. ><TD
  52288. ><PRE
  52289. CLASS="screen"
  52290. >array(2) {
  52291.   ["red"]=>
  52292.   int(2)
  52293.   ["purple"]=>
  52294.   int(4)
  52295. }</PRE
  52296. ></TD
  52297. ></TR
  52298. ></TABLE
  52299. ></DIV
  52300. ></TD
  52301. ></TR
  52302. ></TABLE
  52303. >
  52304.     </P
  52305. ><P
  52306. >      The two keys from the <VAR
  52307. CLASS="literal"
  52308. >key => value</VAR
  52309. > pairs are
  52310.      considered equal only if 
  52311.      <VAR
  52312. CLASS="literal"
  52313. >(string) $key1 === (string) $key2 </VAR
  52314. >. In other words
  52315.      a strict type check is executed so the string representation must be
  52316.      the same.
  52317.     </P
  52318. ><DIV
  52319. CLASS="note"
  52320. ><BLOCKQUOTE
  52321. CLASS="note"
  52322. ><P
  52323. ><B
  52324. >Note: </B
  52325. >
  52326.       Please note that this function only checks one dimension of a n-dimensional
  52327.       array. Of course you can check deeper dimensions by using
  52328.       <VAR
  52329. CLASS="literal"
  52330. >array_diff_key($array1[0], $array2[0]);</VAR
  52331. >.
  52332.      </P
  52333. ></BLOCKQUOTE
  52334. ></DIV
  52335. ><P
  52336. >      See also <A
  52337. HREF="#function.array-diff"
  52338. ><B
  52339. CLASS="function"
  52340. >array_diff()</B
  52341. ></A
  52342. >,
  52343.      <A
  52344. HREF="#function.array-udiff"
  52345. ><B
  52346. CLASS="function"
  52347. >array_udiff()</B
  52348. ></A
  52349. >
  52350.      <A
  52351. HREF="#function.array-diff-assoc"
  52352. ><B
  52353. CLASS="function"
  52354. >array_diff_assoc()</B
  52355. ></A
  52356. >,
  52357.      <A
  52358. HREF="#function.array-diff-uassoc"
  52359. ><B
  52360. CLASS="function"
  52361. >array_diff_uassoc()</B
  52362. ></A
  52363. >,
  52364.      <A
  52365. HREF="#function.array-udiff-assoc"
  52366. ><B
  52367. CLASS="function"
  52368. >array_udiff_assoc()</B
  52369. ></A
  52370. >,
  52371.      <A
  52372. HREF="#function.array-udiff-uassoc"
  52373. ><B
  52374. CLASS="function"
  52375. >array_udiff_uassoc()</B
  52376. ></A
  52377. >,
  52378.      <A
  52379. HREF="#function.array-diff-ukey"
  52380. ><B
  52381. CLASS="function"
  52382. >array_diff_ukey()</B
  52383. ></A
  52384. >,
  52385.      <A
  52386. HREF="#function.array-intersect"
  52387. ><B
  52388. CLASS="function"
  52389. >array_intersect()</B
  52390. ></A
  52391. >,
  52392.      <A
  52393. HREF="#function.array-intersect-assoc"
  52394. ><B
  52395. CLASS="function"
  52396. >array_intersect_assoc()</B
  52397. ></A
  52398. >,
  52399.      <A
  52400. HREF="#function.array-intersect-uassoc"
  52401. ><B
  52402. CLASS="function"
  52403. >array_intersect_uassoc()</B
  52404. ></A
  52405. >,
  52406.      <A
  52407. HREF="#function.array-intersect-key"
  52408. ><B
  52409. CLASS="function"
  52410. >array_intersect_key()</B
  52411. ></A
  52412. > and
  52413.      <A
  52414. HREF="#function.array-intersect-ukey"
  52415. ><B
  52416. CLASS="function"
  52417. >array_intersect_ukey()</B
  52418. ></A
  52419. >.
  52420.     </P
  52421. ></DIV
  52422. ><H1
  52423. ><A
  52424. NAME="function.array-diff-uassoc"
  52425. ></A
  52426. >array_diff_uassoc</H1
  52427. ><DIV
  52428. CLASS="refnamediv"
  52429. ><A
  52430. NAME="AEN8961"
  52431. ></A
  52432. ><P
  52433. >    (PHP 5)</P
  52434. >array_diff_uassoc -- 
  52435.      Computes the difference of arrays with additional index check
  52436.      which is performed by a user supplied callback function
  52437.     </DIV
  52438. ><DIV
  52439. CLASS="refsect1"
  52440. ><A
  52441. NAME="AEN8964"
  52442. ></A
  52443. ><H2
  52444. >Description</H2
  52445. >array <B
  52446. CLASS="methodname"
  52447. >array_diff_uassoc</B
  52448. > ( array array1, array array2 [, array ..., callback key_compare_func])<BR
  52449. ></BR
  52450. ><P
  52451. >      <B
  52452. CLASS="function"
  52453. >array_diff_uassoc()</B
  52454. > returns an <A
  52455. HREF="#language.types.array"
  52456. ><B
  52457. CLASS="type"
  52458. >array</B
  52459. ></A
  52460. >
  52461.      containing all the values from <VAR
  52462. CLASS="parameter"
  52463. >array1</VAR
  52464. >
  52465.      that are not present in any of the other arguments.
  52466.      Note that the keys are used in the comparison unlike
  52467.      <A
  52468. HREF="#function.array-diff"
  52469. ><B
  52470. CLASS="function"
  52471. >array_diff()</B
  52472. ></A
  52473. >. This comparison is done by a user supplied callback function.
  52474.      It must return an integer less than, equal
  52475.      to, or greater than zero if the first argument is considered to
  52476.      be respectively less than, equal to, or greater than the
  52477.      second. This is unlike <A
  52478. HREF="#function.array-diff-assoc"
  52479. ><B
  52480. CLASS="function"
  52481. >array_diff_assoc()</B
  52482. ></A
  52483. > where an
  52484.      internal function for comparing the indices is used.
  52485.     </P
  52486. ><P
  52487. >      <TABLE
  52488. WIDTH="100%"
  52489. BORDER="0"
  52490. CELLPADDING="0"
  52491. CELLSPACING="0"
  52492. CLASS="EXAMPLE"
  52493. ><TR
  52494. ><TD
  52495. ><DIV
  52496. CLASS="example"
  52497. ><A
  52498. NAME="AEN8988"
  52499. ></A
  52500. ><P
  52501. ><B
  52502. >Example 1. <B
  52503. CLASS="function"
  52504. >array_diff_uassoc()</B
  52505. > example</B
  52506. ></P
  52507. ><TABLE
  52508. BORDER="0"
  52509. BGCOLOR="#E0E0E0"
  52510. CELLPADDING="5"
  52511. ><TR
  52512. ><TD
  52513. ><PRE
  52514. CLASS="php"
  52515. ><?php
  52516. function key_compare_func($a, $b) 
  52517. {
  52518.     if ($a === $b) {
  52519.         return 0;
  52520.     }
  52521.     return ($a > $b)? 1:-1;
  52522. }
  52523.  
  52524. $array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
  52525. $array2 = array("a" => "green", "yellow", "red");
  52526. $result = array_diff_uassoc($array1, $array2, "key_compare_func");
  52527. ?></PRE
  52528. ></TD
  52529. ></TR
  52530. ></TABLE
  52531. ><P
  52532. >The above example will output:</P
  52533. ><TABLE
  52534. BORDER="0"
  52535. BGCOLOR="#E0E0E0"
  52536. CELLPADDING="5"
  52537. ><TR
  52538. ><TD
  52539. ><PRE
  52540. CLASS="screen"
  52541. >Array
  52542. (
  52543.     [b] => brown
  52544.     [c] => blue
  52545.     [0] => red
  52546. )</PRE
  52547. ></TD
  52548. ></TR
  52549. ></TABLE
  52550. ></DIV
  52551. ></TD
  52552. ></TR
  52553. ></TABLE
  52554. >
  52555.     </P
  52556. ><P
  52557. >      In our example above you see the <VAR
  52558. CLASS="literal"
  52559. >"a" => "green"</VAR
  52560. >
  52561.      pair is present in both arrays and thus it is not in the ouput from the
  52562.      function. Unlike this, the pair <VAR
  52563. CLASS="literal"
  52564. >0 => "red"</VAR
  52565. >
  52566.      is in the ouput because in the second argument <VAR
  52567. CLASS="literal"
  52568. >"red"</VAR
  52569. >
  52570.      has key which is <VAR
  52571. CLASS="literal"
  52572. >1</VAR
  52573. >.
  52574.     </P
  52575. ><P
  52576. >      The equality of 2 indices is checked by the user supplied callback function.
  52577.     </P
  52578. ><DIV
  52579. CLASS="note"
  52580. ><BLOCKQUOTE
  52581. CLASS="note"
  52582. ><P
  52583. ><B
  52584. >Note: </B
  52585. >
  52586.       Please note that this function only checks one dimension of a n-dimensional
  52587.       array. Of course you can check deeper dimensions by using, for example,
  52588.       <VAR
  52589. CLASS="literal"
  52590. >array_diff_uassoc($array1[0], $array2[0], "key_compare_func");</VAR
  52591. >.
  52592.      </P
  52593. ></BLOCKQUOTE
  52594. ></DIV
  52595. ><P
  52596. >      See also
  52597.      <A
  52598. HREF="#function.array-diff"
  52599. ><B
  52600. CLASS="function"
  52601. >array_diff()</B
  52602. ></A
  52603. >,
  52604.      <A
  52605. HREF="#function.array-diff-assoc"
  52606. ><B
  52607. CLASS="function"
  52608. >array_diff_assoc()</B
  52609. ></A
  52610. >,
  52611.      <A
  52612. HREF="#function.array-udiff"
  52613. ><B
  52614. CLASS="function"
  52615. >array_udiff()</B
  52616. ></A
  52617. >,
  52618.      <A
  52619. HREF="#function.array-udiff-assoc"
  52620. ><B
  52621. CLASS="function"
  52622. >array_udiff_assoc()</B
  52623. ></A
  52624. >, 
  52625.      <A
  52626. HREF="#function.array-udiff-uassoc"
  52627. ><B
  52628. CLASS="function"
  52629. >array_udiff_uassoc()</B
  52630. ></A
  52631. >, 
  52632.      <A
  52633. HREF="#function.array-intersect"
  52634. ><B
  52635. CLASS="function"
  52636. >array_intersect()</B
  52637. ></A
  52638. >,  
  52639.      <A
  52640. HREF="#function.array-intersect-assoc"
  52641. ><B
  52642. CLASS="function"
  52643. >array_intersect_assoc()</B
  52644. ></A
  52645. >,
  52646.      <A
  52647. HREF="#function.array-uintersect"
  52648. ><B
  52649. CLASS="function"
  52650. >array_uintersect()</B
  52651. ></A
  52652. >,  
  52653.      <A
  52654. HREF="#function.array-uintersect-assoc"
  52655. ><B
  52656. CLASS="function"
  52657. >array_uintersect_assoc()</B
  52658. ></A
  52659. > and 
  52660.      <A
  52661. HREF="#function.array-uintersect-uassoc"
  52662. ><B
  52663. CLASS="function"
  52664. >array_uintersect_uassoc()</B
  52665. ></A
  52666. >.
  52667.     </P
  52668. ></DIV
  52669. ><H1
  52670. ><A
  52671. NAME="function.array-diff-ukey"
  52672. ></A
  52673. >array_diff_ukey</H1
  52674. ><DIV
  52675. CLASS="refnamediv"
  52676. ><A
  52677. NAME="AEN9015"
  52678. ></A
  52679. ><P
  52680. >    (no version information, might be only in CVS)</P
  52681. >array_diff_ukey -- Computes the difference of arrays using a callback function on the keys for comparison</DIV
  52682. ><DIV
  52683. CLASS="refsect1"
  52684. ><A
  52685. NAME="AEN9018"
  52686. ></A
  52687. ><H2
  52688. >Description</H2
  52689. >array <B
  52690. CLASS="methodname"
  52691. >array_diff_ukey</B
  52692. > ( array array1, array array2 [, array ..., callback key_compare_func])<BR
  52693. ></BR
  52694. ><P
  52695. >      <B
  52696. CLASS="function"
  52697. >array_diff_ukey()</B
  52698. > returns an array
  52699.      containing all the values of <VAR
  52700. CLASS="parameter"
  52701. >array1</VAR
  52702. >
  52703.      that have keys that are not present in any of the other arguments.
  52704.      Note that the associativity is preserved. This function is like
  52705.      <A
  52706. HREF="#function.array-diff"
  52707. ><B
  52708. CLASS="function"
  52709. >array_diff()</B
  52710. ></A
  52711. > except the comparison is done on the
  52712.      keys instead of the values.
  52713.     </P
  52714. ><P
  52715. >      This comparison is done by a user supplied callback function.
  52716.      It must return an integer less than, equal to, or greater than zero if the
  52717.      first key is considered to be respectively less than, equal to, or
  52718.      greater than the second.
  52719.     </P
  52720. ><P
  52721. >      <TABLE
  52722. WIDTH="100%"
  52723. BORDER="0"
  52724. CELLPADDING="0"
  52725. CELLSPACING="0"
  52726. CLASS="EXAMPLE"
  52727. ><TR
  52728. ><TD
  52729. ><DIV
  52730. CLASS="example"
  52731. ><A
  52732. NAME="AEN9041"
  52733. ></A
  52734. ><P
  52735. ><B
  52736. >Example 1. <B
  52737. CLASS="function"
  52738. >array_diff_ukey()</B
  52739. > example</B
  52740. ></P
  52741. ><TABLE
  52742. BORDER="0"
  52743. BGCOLOR="#E0E0E0"
  52744. CELLPADDING="5"
  52745. ><TR
  52746. ><TD
  52747. ><PRE
  52748. CLASS="php"
  52749. ><?php
  52750. function key_compare_func($key1, $key2)
  52751. {
  52752.     if ($key1 == $key2)
  52753.         return 0;
  52754.     else if ($key1 > $key2)
  52755.         return 1;
  52756.     else
  52757.         return -1;
  52758. }
  52759.  
  52760. $array1 = array('blue'  => 1, 'red'  => 2, 'green'  => 3, 'purple' => 4);
  52761. $array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan'   => 8);
  52762.  
  52763. var_dump(array_diff_ukey($array1, $array2, 'key_compare_func'));
  52764. ?></PRE
  52765. ></TD
  52766. ></TR
  52767. ></TABLE
  52768. ><P
  52769. >The above example will output:</P
  52770. ><TABLE
  52771. BORDER="0"
  52772. BGCOLOR="#E0E0E0"
  52773. CELLPADDING="5"
  52774. ><TR
  52775. ><TD
  52776. ><PRE
  52777. CLASS="screen"
  52778. >array(2) {
  52779.   ["red"]=>
  52780.   int(2)
  52781.   ["purple"]=>
  52782.   int(4)
  52783. }</PRE
  52784. ></TD
  52785. ></TR
  52786. ></TABLE
  52787. ></DIV
  52788. ></TD
  52789. ></TR
  52790. ></TABLE
  52791. >
  52792.     </P
  52793. ><P
  52794. >      The two keys from the <VAR
  52795. CLASS="literal"
  52796. >key => value</VAR
  52797. > pairs are
  52798.      considered equal only if 
  52799.      <VAR
  52800. CLASS="literal"
  52801. >(string) $key1 === (string) $key2 </VAR
  52802. >. In other words
  52803.      a strict type check is executed so the string representation must be
  52804.      the same.
  52805.     </P
  52806. ><DIV
  52807. CLASS="note"
  52808. ><BLOCKQUOTE
  52809. CLASS="note"
  52810. ><P
  52811. ><B
  52812. >Note: </B
  52813. >
  52814.       Please note that this function only checks one dimension of a n-dimensional
  52815.       array. Of course you can check deeper dimensions by using
  52816.       <VAR
  52817. CLASS="literal"
  52818. >array_diff_ukey($array1[0], $array2[0], 'callback_func');</VAR
  52819. >.
  52820.      </P
  52821. ></BLOCKQUOTE
  52822. ></DIV
  52823. ><P
  52824. >      See also <A
  52825. HREF="#function.array-diff"
  52826. ><B
  52827. CLASS="function"
  52828. >array_diff()</B
  52829. ></A
  52830. >,
  52831.      <A
  52832. HREF="#function.array-udiff"
  52833. ><B
  52834. CLASS="function"
  52835. >array_udiff()</B
  52836. ></A
  52837. >
  52838.      <A
  52839. HREF="#function.array-diff-assoc"
  52840. ><B
  52841. CLASS="function"
  52842. >array_diff_assoc()</B
  52843. ></A
  52844. >,
  52845.      <A
  52846. HREF="#function.array-diff-uassoc"
  52847. ><B
  52848. CLASS="function"
  52849. >array_diff_uassoc()</B
  52850. ></A
  52851. >,
  52852.      <A
  52853. HREF="#function.array-udiff-assoc"
  52854. ><B
  52855. CLASS="function"
  52856. >array_udiff_assoc()</B
  52857. ></A
  52858. >,
  52859.      <A
  52860. HREF="#function.array-udiff-uassoc"
  52861. ><B
  52862. CLASS="function"
  52863. >array_udiff_uassoc()</B
  52864. ></A
  52865. >,
  52866.      <A
  52867. HREF="#function.array-diff-key"
  52868. ><B
  52869. CLASS="function"
  52870. >array_diff_key()</B
  52871. ></A
  52872. >,
  52873.      <A
  52874. HREF="#function.array-intersect"
  52875. ><B
  52876. CLASS="function"
  52877. >array_intersect()</B
  52878. ></A
  52879. >,
  52880.      <A
  52881. HREF="#function.array-intersect-assoc"
  52882. ><B
  52883. CLASS="function"
  52884. >array_intersect_assoc()</B
  52885. ></A
  52886. >,
  52887.      <A
  52888. HREF="#function.array-intersect-uassoc"
  52889. ><B
  52890. CLASS="function"
  52891. >array_intersect_uassoc()</B
  52892. ></A
  52893. >,
  52894.      <A
  52895. HREF="#function.array-intersect-key"
  52896. ><B
  52897. CLASS="function"
  52898. >array_intersect_key()</B
  52899. ></A
  52900. > and
  52901.      <A
  52902. HREF="#function.array-intersect-ukey"
  52903. ><B
  52904. CLASS="function"
  52905. >array_intersect_ukey()</B
  52906. ></A
  52907. >.
  52908.     </P
  52909. ></DIV
  52910. ><H1
  52911. ><A
  52912. NAME="function.array-diff"
  52913. ></A
  52914. >array_diff</H1
  52915. ><DIV
  52916. CLASS="refnamediv"
  52917. ><A
  52918. NAME="AEN9067"
  52919. ></A
  52920. ><P
  52921. >    (PHP 4 >= 4.0.1, PHP 5)</P
  52922. >array_diff -- Computes the difference of arrays</DIV
  52923. ><DIV
  52924. CLASS="refsect1"
  52925. ><A
  52926. NAME="AEN9070"
  52927. ></A
  52928. ><H2
  52929. >Description</H2
  52930. >array <B
  52931. CLASS="methodname"
  52932. >array_diff</B
  52933. > ( array array1, array array2 [, array ...])<BR
  52934. ></BR
  52935. ><P
  52936. >      <B
  52937. CLASS="function"
  52938. >array_diff()</B
  52939. > returns an array
  52940.      containing all the values of <VAR
  52941. CLASS="parameter"
  52942. >array1</VAR
  52943. >
  52944.      that are not present in any of the other arguments.
  52945.      Note that keys are preserved.
  52946.     </P
  52947. ><P
  52948. >      <TABLE
  52949. WIDTH="100%"
  52950. BORDER="0"
  52951. CELLPADDING="0"
  52952. CELLSPACING="0"
  52953. CLASS="EXAMPLE"
  52954. ><TR
  52955. ><TD
  52956. ><DIV
  52957. CLASS="example"
  52958. ><A
  52959. NAME="AEN9088"
  52960. ></A
  52961. ><P
  52962. ><B
  52963. >Example 1. <B
  52964. CLASS="function"
  52965. >array_diff()</B
  52966. > example</B
  52967. ></P
  52968. ><TABLE
  52969. BORDER="0"
  52970. BGCOLOR="#E0E0E0"
  52971. CELLPADDING="5"
  52972. ><TR
  52973. ><TD
  52974. ><PRE
  52975. CLASS="php"
  52976. ><?php
  52977. $array1 = array("a" => "green", "red", "blue", "red");
  52978. $array2 = array("b" => "green", "yellow", "red");
  52979. $result = array_diff($array1, $array2);
  52980.  
  52981. print_r($result);
  52982. ?></PRE
  52983. ></TD
  52984. ></TR
  52985. ></TABLE
  52986. ><P
  52987. >        Multiple occurrences in $array1 are all treated the same way.
  52988.        This will output :
  52989.       </P
  52990. ><TABLE
  52991. BORDER="0"
  52992. BGCOLOR="#E0E0E0"
  52993. CELLPADDING="5"
  52994. ><TR
  52995. ><TD
  52996. ><PRE
  52997. CLASS="screen"
  52998. >Array
  52999. (
  53000.     [1] => blue
  53001. )</PRE
  53002. ></TD
  53003. ></TR
  53004. ></TABLE
  53005. ></DIV
  53006. ></TD
  53007. ></TR
  53008. ></TABLE
  53009. >
  53010.     </P
  53011. ><DIV
  53012. CLASS="note"
  53013. ><BLOCKQUOTE
  53014. CLASS="note"
  53015. ><P
  53016. ><B
  53017. >Note: </B
  53018. >
  53019.       Two elements are considered equal if and only if
  53020.       <VAR
  53021. CLASS="literal"
  53022. >(string) $elem1 === (string) $elem2</VAR
  53023. >. In words:
  53024.       when the string representation is the same.
  53025.       
  53026.      </P
  53027. ></BLOCKQUOTE
  53028. ></DIV
  53029. ><DIV
  53030. CLASS="note"
  53031. ><BLOCKQUOTE
  53032. CLASS="note"
  53033. ><P
  53034. ><B
  53035. >Note: </B
  53036. >
  53037.       Please note that this function only checks one dimension of a n-dimensional
  53038.       array. Of course you can check deeper dimensions by using
  53039.       <VAR
  53040. CLASS="literal"
  53041. >array_diff($array1[0], $array2[0]);</VAR
  53042. >.
  53043.      </P
  53044. ></BLOCKQUOTE
  53045. ></DIV
  53046. ><DIV
  53047. CLASS="warning"
  53048. ><P
  53049. ></P
  53050. ><TABLE
  53051. CLASS="warning"
  53052. BORDER="1"
  53053. WIDTH="100%"
  53054. ><TR
  53055. ><TD
  53056. ALIGN="CENTER"
  53057. ><B
  53058. >Warning</B
  53059. ></TD
  53060. ></TR
  53061. ><TR
  53062. ><TD
  53063. ALIGN="LEFT"
  53064. ><P
  53065. >       This was broken in PHP 4.0.4!
  53066.       
  53067.      </P
  53068. ></TD
  53069. ></TR
  53070. ></TABLE
  53071. ></DIV
  53072. ><P
  53073. >      See also <A
  53074. HREF="#function.array-diff-assoc"
  53075. ><B
  53076. CLASS="function"
  53077. >array_diff_assoc()</B
  53078. ></A
  53079. >,
  53080.      <A
  53081. HREF="#function.array-intersect"
  53082. ><B
  53083. CLASS="function"
  53084. >array_intersect()</B
  53085. ></A
  53086. >, and
  53087.      <A
  53088. HREF="#function.array-intersect-assoc"
  53089. ><B
  53090. CLASS="function"
  53091. >array_intersect_assoc()</B
  53092. ></A
  53093. >.
  53094.     </P
  53095. ></DIV
  53096. ><H1
  53097. ><A
  53098. NAME="function.array-fill"
  53099. ></A
  53100. >array_fill</H1
  53101. ><DIV
  53102. CLASS="refnamediv"
  53103. ><A
  53104. NAME="AEN9107"
  53105. ></A
  53106. ><P
  53107. >    (PHP 4 >= 4.2.0, PHP 5)</P
  53108. >array_fill -- Fill an array with values</DIV
  53109. ><DIV
  53110. CLASS="refsect1"
  53111. ><A
  53112. NAME="AEN9110"
  53113. ></A
  53114. ><H2
  53115. >Description</H2
  53116. >array <B
  53117. CLASS="methodname"
  53118. >array_fill</B
  53119. > ( int start_index, int num, mixed value)<BR
  53120. ></BR
  53121. ><P
  53122. >      <B
  53123. CLASS="function"
  53124. >array_fill()</B
  53125. > fills an array with
  53126.      <VAR
  53127. CLASS="parameter"
  53128. >num</VAR
  53129. > entries of the value of the
  53130.      <VAR
  53131. CLASS="parameter"
  53132. >value</VAR
  53133. > parameter, keys starting at the
  53134.      <VAR
  53135. CLASS="parameter"
  53136. >start_index</VAR
  53137. > parameter.  Note that <VAR
  53138. CLASS="parameter"
  53139. >      num</VAR
  53140. > must be a number greater than zero, or PHP will throw
  53141.      a warning.
  53142.     </P
  53143. ><P
  53144. >      <TABLE
  53145. WIDTH="100%"
  53146. BORDER="0"
  53147. CELLPADDING="0"
  53148. CELLSPACING="0"
  53149. CLASS="EXAMPLE"
  53150. ><TR
  53151. ><TD
  53152. ><DIV
  53153. CLASS="example"
  53154. ><A
  53155. NAME="AEN9131"
  53156. ></A
  53157. ><P
  53158. ><B
  53159. >Example 1. <B
  53160. CLASS="function"
  53161. >array_fill()</B
  53162. > example</B
  53163. ></P
  53164. ><TABLE
  53165. BORDER="0"
  53166. BGCOLOR="#E0E0E0"
  53167. CELLPADDING="5"
  53168. ><TR
  53169. ><TD
  53170. ><PRE
  53171. CLASS="php"
  53172. ><?php
  53173. $a = array_fill(5, 6, 'banana');
  53174. print_r($a);
  53175. ?></PRE
  53176. ></TD
  53177. ></TR
  53178. ></TABLE
  53179. ><P
  53180. >        <VAR
  53181. CLASS="varname"
  53182. >$a</VAR
  53183. > now is:
  53184.       </P
  53185. ><TABLE
  53186. BORDER="0"
  53187. BGCOLOR="#E0E0E0"
  53188. CELLPADDING="5"
  53189. ><TR
  53190. ><TD
  53191. ><PRE
  53192. CLASS="screen"
  53193. >Array
  53194. (
  53195.     [5]  => banana
  53196.     [6]  => banana
  53197.     [7]  => banana
  53198.     [8]  => banana
  53199.     [9]  => banana
  53200.     [10] => banana
  53201. )</PRE
  53202. ></TD
  53203. ></TR
  53204. ></TABLE
  53205. ></DIV
  53206. ></TD
  53207. ></TR
  53208. ></TABLE
  53209. >
  53210.     </P
  53211. ><P
  53212. >      See also <A
  53213. HREF="#function.str-repeat"
  53214. ><B
  53215. CLASS="function"
  53216. >str_repeat()</B
  53217. ></A
  53218. > and
  53219.      <A
  53220. HREF="#function.range"
  53221. ><B
  53222. CLASS="function"
  53223. >range()</B
  53224. ></A
  53225. >.
  53226.     </P
  53227. ></DIV
  53228. ><H1
  53229. ><A
  53230. NAME="function.array-filter"
  53231. ></A
  53232. >array_filter</H1
  53233. ><DIV
  53234. CLASS="refnamediv"
  53235. ><A
  53236. NAME="AEN9142"
  53237. ></A
  53238. ><P
  53239. >    (PHP 4 >= 4.0.6, PHP 5)</P
  53240. >array_filter -- 
  53241.      Filters elements of an array using a callback function
  53242.     </DIV
  53243. ><DIV
  53244. CLASS="refsect1"
  53245. ><A
  53246. NAME="AEN9145"
  53247. ></A
  53248. ><H2
  53249. >Description</H2
  53250. >array <B
  53251. CLASS="methodname"
  53252. >array_filter</B
  53253. > ( array input [, callback callback])<BR
  53254. ></BR
  53255. ><P
  53256. >      <B
  53257. CLASS="function"
  53258. >array_filter()</B
  53259. > iterates over each value in
  53260.      the <VAR
  53261. CLASS="parameter"
  53262. >input</VAR
  53263. > array passing them to the
  53264.      <VAR
  53265. CLASS="parameter"
  53266. >callback</VAR
  53267. > function.  If the <VAR
  53268. CLASS="parameter"
  53269. >      callback</VAR
  53270. > function returns true, the current
  53271.      value from <VAR
  53272. CLASS="parameter"
  53273. >input</VAR
  53274. > is returned into the
  53275.      result array.  Array keys are preserved.
  53276.     </P
  53277. ><P
  53278. >      <TABLE
  53279. WIDTH="100%"
  53280. BORDER="0"
  53281. CELLPADDING="0"
  53282. CELLSPACING="0"
  53283. CLASS="EXAMPLE"
  53284. ><TR
  53285. ><TD
  53286. ><DIV
  53287. CLASS="example"
  53288. ><A
  53289. NAME="AEN9163"
  53290. ></A
  53291. ><P
  53292. ><B
  53293. >Example 1. <B
  53294. CLASS="function"
  53295. >array_filter()</B
  53296. > example</B
  53297. ></P
  53298. ><TABLE
  53299. BORDER="0"
  53300. BGCOLOR="#E0E0E0"
  53301. CELLPADDING="5"
  53302. ><TR
  53303. ><TD
  53304. ><PRE
  53305. CLASS="php"
  53306. ><?php
  53307. function odd($var) 
  53308. {
  53309.     return($var % 2 == 1);
  53310. }
  53311.  
  53312. function even($var) 
  53313. {
  53314.     return($var % 2 == 0);
  53315. }
  53316.  
  53317. $array1 = array("a"=>1, "b"=>2, "c"=>3, "d"=>4, "e"=>5);
  53318. $array2 = array(6, 7, 8, 9, 10, 11, 12);
  53319.  
  53320. echo "Odd :\n";
  53321. print_r(array_filter($array1, "odd"));
  53322. echo "Even:\n";
  53323. print_r(array_filter($array2, "even"));
  53324. ?></PRE
  53325. ></TD
  53326. ></TR
  53327. ></TABLE
  53328. ><P
  53329. >The above example will output:</P
  53330. ><TABLE
  53331. BORDER="0"
  53332. BGCOLOR="#E0E0E0"
  53333. CELLPADDING="5"
  53334. ><TR
  53335. ><TD
  53336. ><PRE
  53337. CLASS="php"
  53338. >Odd :
  53339. Array
  53340. (
  53341.     [a] => 1
  53342.     [c] => 3
  53343.     [e] => 5
  53344. )
  53345. Even:
  53346. Array
  53347. (
  53348.     [0] => 6
  53349.     [2] => 8
  53350.     [4] => 10
  53351.     [6] => 12
  53352. )</PRE
  53353. ></TD
  53354. ></TR
  53355. ></TABLE
  53356. ></DIV
  53357. ></TD
  53358. ></TR
  53359. ></TABLE
  53360. >
  53361.     </P
  53362. ><P
  53363. >      Users may not change the array itself from the callback
  53364.      function. e.g. Add/delete an element, unset the array that
  53365.      <B
  53366. CLASS="function"
  53367. >array_filter()</B
  53368. > is applied to. If the array
  53369.      is changed, the behavior of this function is undefined.
  53370.     </P
  53371. ><P
  53372. >      If the <VAR
  53373. CLASS="parameter"
  53374. >callback</VAR
  53375. > function is not supplied,
  53376.      <B
  53377. CLASS="function"
  53378. >array_filter()</B
  53379. > will remove all the entries of
  53380.      <VAR
  53381. CLASS="parameter"
  53382. >input</VAR
  53383. > that are equal to <TT
  53384. CLASS="constant"
  53385. ><B
  53386. >FALSE</B
  53387. ></TT
  53388. >. See <A
  53389. HREF="#language.types.boolean.casting"
  53390. >converting to boolean</A
  53391. > 
  53392.      for more information.
  53393.     </P
  53394. ><P
  53395. >      <TABLE
  53396. WIDTH="100%"
  53397. BORDER="0"
  53398. CELLPADDING="0"
  53399. CELLSPACING="0"
  53400. CLASS="EXAMPLE"
  53401. ><TR
  53402. ><TD
  53403. ><DIV
  53404. CLASS="example"
  53405. ><A
  53406. NAME="AEN9178"
  53407. ></A
  53408. ><P
  53409. ><B
  53410. >Example 2. <B
  53411. CLASS="function"
  53412. >array_filter()</B
  53413. > without
  53414.       <VAR
  53415. CLASS="parameter"
  53416. >callback</VAR
  53417. ></B
  53418. ></P
  53419. ><TABLE
  53420. BORDER="0"
  53421. BGCOLOR="#E0E0E0"
  53422. CELLPADDING="5"
  53423. ><TR
  53424. ><TD
  53425. ><PRE
  53426. CLASS="php"
  53427. ><?php
  53428.  
  53429. $entry = array(
  53430.              0 => 'foo',
  53431.              1 => false,
  53432.              2 => -1,
  53433.              3 => null,
  53434.              4 => ''
  53435.           );
  53436.  
  53437. print_r(array_filter($entry));
  53438. ?></PRE
  53439. ></TD
  53440. ></TR
  53441. ></TABLE
  53442. ><P
  53443. >The above example will output:</P
  53444. ><TABLE
  53445. BORDER="0"
  53446. BGCOLOR="#E0E0E0"
  53447. CELLPADDING="5"
  53448. ><TR
  53449. ><TD
  53450. ><PRE
  53451. CLASS="screen"
  53452. >Array
  53453. (
  53454.     [0] => foo
  53455.     [2] => -1
  53456. )</PRE
  53457. ></TD
  53458. ></TR
  53459. ></TABLE
  53460. ></DIV
  53461. ></TD
  53462. ></TR
  53463. ></TABLE
  53464. >
  53465.     </P
  53466. ><P
  53467. >      See also <A
  53468. HREF="#function.array-map"
  53469. ><B
  53470. CLASS="function"
  53471. >array_map()</B
  53472. ></A
  53473. >,
  53474.      <A
  53475. HREF="#function.array-reduce"
  53476. ><B
  53477. CLASS="function"
  53478. >array_reduce()</B
  53479. ></A
  53480. >, and <A
  53481. HREF="#function.array-walk"
  53482. ><B
  53483. CLASS="function"
  53484. >array_walk()</B
  53485. ></A
  53486. >.
  53487.     </P
  53488. ></DIV
  53489. ><H1
  53490. ><A
  53491. NAME="function.array-flip"
  53492. ></A
  53493. >array_flip</H1
  53494. ><DIV
  53495. CLASS="refnamediv"
  53496. ><A
  53497. NAME="AEN9190"
  53498. ></A
  53499. ><P
  53500. >    (PHP 4 , PHP 5)</P
  53501. >array_flip -- Exchanges all keys with their associated values in an array</DIV
  53502. ><DIV
  53503. CLASS="refsect1"
  53504. ><A
  53505. NAME="AEN9193"
  53506. ></A
  53507. ><H2
  53508. >Description</H2
  53509. >array <B
  53510. CLASS="methodname"
  53511. >array_flip</B
  53512. > ( array trans)<BR
  53513. ></BR
  53514. ><P
  53515. >      <B
  53516. CLASS="function"
  53517. >array_flip()</B
  53518. > returns an <A
  53519. HREF="#language.types.array"
  53520. ><B
  53521. CLASS="type"
  53522. >array</B
  53523. ></A
  53524. > in flip
  53525.      order, i.e. keys from <VAR
  53526. CLASS="parameter"
  53527. >trans</VAR
  53528. > become values and values
  53529.      from <VAR
  53530. CLASS="parameter"
  53531. >trans</VAR
  53532. > become keys.
  53533.     </P
  53534. ><P
  53535. >      Note that the values of <VAR
  53536. CLASS="parameter"
  53537. >trans</VAR
  53538. > need to be valid
  53539.      keys, i.e. they need to be either <A
  53540. HREF="#language.types.integer"
  53541. ><B
  53542. CLASS="type"
  53543. >integer</B
  53544. ></A
  53545. > or
  53546.      <A
  53547. HREF="#language.types.string"
  53548. ><B
  53549. CLASS="type"
  53550. >string</B
  53551. ></A
  53552. >. A warning will be emitted if a value has the wrong
  53553.      type, and the key/value pair in question <SPAN
  53554. CLASS="emphasis"
  53555. ><I
  53556. CLASS="emphasis"
  53557. >will not be
  53558.      flipped</I
  53559. ></SPAN
  53560. >.
  53561.     </P
  53562. ><P
  53563. >      If a value has several occurrences, the latest key will be
  53564.      used as its values, and all others will be lost.
  53565.     </P
  53566. ><P
  53567. >      <B
  53568. CLASS="function"
  53569. >array_flip()</B
  53570. > returns <TT
  53571. CLASS="constant"
  53572. ><B
  53573. >FALSE</B
  53574. ></TT
  53575. >
  53576.      if it fails.
  53577.     </P
  53578. ><P
  53579. >      <TABLE
  53580. WIDTH="100%"
  53581. BORDER="0"
  53582. CELLPADDING="0"
  53583. CELLSPACING="0"
  53584. CLASS="EXAMPLE"
  53585. ><TR
  53586. ><TD
  53587. ><DIV
  53588. CLASS="example"
  53589. ><A
  53590. NAME="AEN9216"
  53591. ></A
  53592. ><P
  53593. ><B
  53594. >Example 1. <B
  53595. CLASS="function"
  53596. >array_flip()</B
  53597. > example</B
  53598. ></P
  53599. ><TABLE
  53600. BORDER="0"
  53601. BGCOLOR="#E0E0E0"
  53602. CELLPADDING="5"
  53603. ><TR
  53604. ><TD
  53605. ><PRE
  53606. CLASS="php"
  53607. ><?php
  53608. $trans = array_flip($trans);
  53609. $original = strtr($str, $trans);
  53610. ?></PRE
  53611. ></TD
  53612. ></TR
  53613. ></TABLE
  53614. ></DIV
  53615. ></TD
  53616. ></TR
  53617. ></TABLE
  53618. >
  53619.     </P
  53620. ><P
  53621. >      <TABLE
  53622. WIDTH="100%"
  53623. BORDER="0"
  53624. CELLPADDING="0"
  53625. CELLSPACING="0"
  53626. CLASS="EXAMPLE"
  53627. ><TR
  53628. ><TD
  53629. ><DIV
  53630. CLASS="example"
  53631. ><A
  53632. NAME="AEN9221"
  53633. ></A
  53634. ><P
  53635. ><B
  53636. >Example 2. <B
  53637. CLASS="function"
  53638. >array_flip()</B
  53639. > example : collision</B
  53640. ></P
  53641. ><TABLE
  53642. BORDER="0"
  53643. BGCOLOR="#E0E0E0"
  53644. CELLPADDING="5"
  53645. ><TR
  53646. ><TD
  53647. ><PRE
  53648. CLASS="php"
  53649. ><?php
  53650. $trans = array("a" => 1, "b" => 1, "c" => 2);
  53651. $trans = array_flip($trans);
  53652. print_r($trans);
  53653. ?></PRE
  53654. ></TD
  53655. ></TR
  53656. ></TABLE
  53657. ><P
  53658. >        now <VAR
  53659. CLASS="varname"
  53660. >$trans</VAR
  53661. > is:
  53662.       </P
  53663. ><TABLE
  53664. BORDER="0"
  53665. BGCOLOR="#E0E0E0"
  53666. CELLPADDING="5"
  53667. ><TR
  53668. ><TD
  53669. ><PRE
  53670. CLASS="screen"
  53671. >Array
  53672. (
  53673.     [1] => b
  53674.     [2] => c
  53675. )</PRE
  53676. ></TD
  53677. ></TR
  53678. ></TABLE
  53679. ></DIV
  53680. ></TD
  53681. ></TR
  53682. ></TABLE
  53683. >
  53684.     </P
  53685. ><P
  53686. >      See also <A
  53687. HREF="#function.array-values"
  53688. ><B
  53689. CLASS="function"
  53690. >array_values()</B
  53691. ></A
  53692. >,
  53693.      <A
  53694. HREF="#function.array-keys"
  53695. ><B
  53696. CLASS="function"
  53697. >array_keys()</B
  53698. ></A
  53699. >, and
  53700.      <A
  53701. HREF="#function.array-reverse"
  53702. ><B
  53703. CLASS="function"
  53704. >array_reverse()</B
  53705. ></A
  53706. >.
  53707.     </P
  53708. ></DIV
  53709. ><H1
  53710. ><A
  53711. NAME="function.array-intersect-assoc"
  53712. ></A
  53713. >array_intersect_assoc</H1
  53714. ><DIV
  53715. CLASS="refnamediv"
  53716. ><A
  53717. NAME="AEN9233"
  53718. ></A
  53719. ><P
  53720. >    (PHP 4 >= 4.3.0, PHP 5)</P
  53721. >array_intersect_assoc -- Computes the intersection of arrays with additional index check</DIV
  53722. ><DIV
  53723. CLASS="refsect1"
  53724. ><A
  53725. NAME="AEN9236"
  53726. ></A
  53727. ><H2
  53728. >Description</H2
  53729. >array <B
  53730. CLASS="methodname"
  53731. >array_intersect_assoc</B
  53732. > ( array array1, array array2 [, array ...])<BR
  53733. ></BR
  53734. ><P
  53735. >      <B
  53736. CLASS="function"
  53737. >array_intersect_assoc()</B
  53738. > returns an array
  53739.      containing all the values of <VAR
  53740. CLASS="parameter"
  53741. >array1</VAR
  53742. >
  53743.      that are present in all the arguments. Note that the keys are used in
  53744.      the comparison unlike in <A
  53745. HREF="#function.array-intersect"
  53746. ><B
  53747. CLASS="function"
  53748. >array_intersect()</B
  53749. ></A
  53750. >.
  53751.     </P
  53752. ><P
  53753. >      <TABLE
  53754. WIDTH="100%"
  53755. BORDER="0"
  53756. CELLPADDING="0"
  53757. CELLSPACING="0"
  53758. CLASS="EXAMPLE"
  53759. ><TR
  53760. ><TD
  53761. ><DIV
  53762. CLASS="example"
  53763. ><A
  53764. NAME="AEN9255"
  53765. ></A
  53766. ><P
  53767. ><B
  53768. >Example 1. <B
  53769. CLASS="function"
  53770. >array_intersect_assoc()</B
  53771. > example</B
  53772. ></P
  53773. ><TABLE
  53774. BORDER="0"
  53775. BGCOLOR="#E0E0E0"
  53776. CELLPADDING="5"
  53777. ><TR
  53778. ><TD
  53779. ><PRE
  53780. CLASS="php"
  53781. ><?php
  53782. $array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
  53783. $array2 = array("a" => "green", "yellow", "red");
  53784. $result_array = array_intersect_assoc($array1, $array2);
  53785. ?></PRE
  53786. ></TD
  53787. ></TR
  53788. ></TABLE
  53789. ><P
  53790. >        $result_array will look like:
  53791.       </P
  53792. ><TABLE
  53793. BORDER="0"
  53794. BGCOLOR="#E0E0E0"
  53795. CELLPADDING="5"
  53796. ><TR
  53797. ><TD
  53798. ><PRE
  53799. CLASS="screen"
  53800. >Array
  53801. (
  53802.     [a] => green
  53803. )</PRE
  53804. ></TD
  53805. ></TR
  53806. ></TABLE
  53807. ></DIV
  53808. ></TD
  53809. ></TR
  53810. ></TABLE
  53811. >
  53812.     </P
  53813. ><P
  53814. >      In our example you see that only the pair <VAR
  53815. CLASS="literal"
  53816. >"a" =>
  53817.      "green"</VAR
  53818. > is present in both arrays and thus is returned. 
  53819.      The value <VAR
  53820. CLASS="literal"
  53821. >"red"</VAR
  53822. > is not returned because in 
  53823.      <VAR
  53824. CLASS="varname"
  53825. >$array1</VAR
  53826. > its key is <VAR
  53827. CLASS="literal"
  53828. >0</VAR
  53829. > while
  53830.      the key of "red" in <VAR
  53831. CLASS="varname"
  53832. >$array2</VAR
  53833. > is 
  53834.      <VAR
  53835. CLASS="literal"
  53836. >1</VAR
  53837. >.
  53838.     </P
  53839. ><P
  53840. >      The two values from the <VAR
  53841. CLASS="literal"
  53842. >key => value</VAR
  53843. > pairs are
  53844.      considered equal only if 
  53845.      <VAR
  53846. CLASS="literal"
  53847. >(string) $elem1 === (string) $elem2 </VAR
  53848. >. In other words
  53849.      a strict type check is executed so the string representation must be
  53850.      the same. 
  53851.      
  53852.     </P
  53853. ><P
  53854. >      See also <A
  53855. HREF="#function.array-intersect"
  53856. ><B
  53857. CLASS="function"
  53858. >array_intersect()</B
  53859. ></A
  53860. >,
  53861.      <A
  53862. HREF="#function.array-uintersect-assoc"
  53863. ><B
  53864. CLASS="function"
  53865. >array_uintersect_assoc()</B
  53866. ></A
  53867. >,
  53868.      <A
  53869. HREF="#function.array-intersect-uassoc"
  53870. ><B
  53871. CLASS="function"
  53872. >array_intersect_uassoc()</B
  53873. ></A
  53874. >,
  53875.      <A
  53876. HREF="#function.array-uintersect-uassoc"
  53877. ><B
  53878. CLASS="function"
  53879. >array_uintersect_uassoc()</B
  53880. ></A
  53881. >,
  53882.      <A
  53883. HREF="#function.array-diff"
  53884. ><B
  53885. CLASS="function"
  53886. >array_diff()</B
  53887. ></A
  53888. > and
  53889.      <A
  53890. HREF="#function.array-diff-assoc"
  53891. ><B
  53892. CLASS="function"
  53893. >array_diff_assoc()</B
  53894. ></A
  53895. >.
  53896.     </P
  53897. ></DIV
  53898. ><H1
  53899. ><A
  53900. NAME="function.array-intersect-key"
  53901. ></A
  53902. >array_intersect_key</H1
  53903. ><DIV
  53904. CLASS="refnamediv"
  53905. ><A
  53906. NAME="AEN9279"
  53907. ></A
  53908. ><P
  53909. >    (no version information, might be only in CVS)</P
  53910. >array_intersect_key -- Computes the intersection of arrays using keys for comparison</DIV
  53911. ><DIV
  53912. CLASS="refsect1"
  53913. ><A
  53914. NAME="AEN9282"
  53915. ></A
  53916. ><H2
  53917. >Description</H2
  53918. >array <B
  53919. CLASS="methodname"
  53920. >array_intersect_key</B
  53921. > ( array array1, array array2 [, array ...])<BR
  53922. ></BR
  53923. ><P
  53924. >      <B
  53925. CLASS="function"
  53926. >array_intersect_key()</B
  53927. > returns an array
  53928.      containing all the values of <VAR
  53929. CLASS="parameter"
  53930. >array1</VAR
  53931. >
  53932.      which have matching keys that are present in all the arguments.
  53933.     </P
  53934. ><P
  53935. >      <TABLE
  53936. WIDTH="100%"
  53937. BORDER="0"
  53938. CELLPADDING="0"
  53939. CELLSPACING="0"
  53940. CLASS="EXAMPLE"
  53941. ><TR
  53942. ><TD
  53943. ><DIV
  53944. CLASS="example"
  53945. ><A
  53946. NAME="AEN9300"
  53947. ></A
  53948. ><P
  53949. ><B
  53950. >Example 1. <B
  53951. CLASS="function"
  53952. >array_intersect_key()</B
  53953. > example</B
  53954. ></P
  53955. ><TABLE
  53956. BORDER="0"
  53957. BGCOLOR="#E0E0E0"
  53958. CELLPADDING="5"
  53959. ><TR
  53960. ><TD
  53961. ><PRE
  53962. CLASS="php"
  53963. ><?php
  53964. $array1 = array('blue'  => 1, 'red'  => 2, 'green'  => 3, 'purple' => 4);
  53965. $array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan'   => 8);
  53966.  
  53967. var_dump(array_intersect_key($array1, $array2));
  53968. ?></PRE
  53969. ></TD
  53970. ></TR
  53971. ></TABLE
  53972. ><P
  53973. >The above example will output:</P
  53974. ><TABLE
  53975. BORDER="0"
  53976. BGCOLOR="#E0E0E0"
  53977. CELLPADDING="5"
  53978. ><TR
  53979. ><TD
  53980. ><PRE
  53981. CLASS="screen"
  53982. >array(2) {
  53983.   ["blue"]=>
  53984.   int(1)
  53985.   ["green"]=>
  53986.   int(3)
  53987. })</PRE
  53988. ></TD
  53989. ></TR
  53990. ></TABLE
  53991. ></DIV
  53992. ></TD
  53993. ></TR
  53994. ></TABLE
  53995. >
  53996.     </P
  53997. ><P
  53998. >      In our example you see that only the keys <VAR
  53999. CLASS="literal"
  54000. >'blue'</VAR
  54001. >
  54002.      and <VAR
  54003. CLASS="literal"
  54004. >'green'</VAR
  54005. > are present in both arrays and thus
  54006.      returned. Also notice that the values for the keys
  54007.      <VAR
  54008. CLASS="literal"
  54009. >'blue'</VAR
  54010. > and <VAR
  54011. CLASS="literal"
  54012. >'green'</VAR
  54013. > differ between
  54014.      the two arrays. A match still occurs because only the keys are checked.
  54015.      The values returned are those of <VAR
  54016. CLASS="parameter"
  54017. >array1</VAR
  54018. >.
  54019.     </P
  54020. ><P
  54021. >      The two keys from the <VAR
  54022. CLASS="literal"
  54023. >key => value</VAR
  54024. > pairs are
  54025.      considered equal only if 
  54026.      <VAR
  54027. CLASS="literal"
  54028. >(string) $key1 === (string) $key2 </VAR
  54029. >. In other words
  54030.      a strict type check is executed so the string representation must be
  54031.      the same.
  54032.     </P
  54033. ><P
  54034. >      See also <A
  54035. HREF="#function.array-diff"
  54036. ><B
  54037. CLASS="function"
  54038. >array_diff()</B
  54039. ></A
  54040. >,
  54041.      <A
  54042. HREF="#function.array-udiff"
  54043. ><B
  54044. CLASS="function"
  54045. >array_udiff()</B
  54046. ></A
  54047. >
  54048.      <A
  54049. HREF="#function.array-diff-assoc"
  54050. ><B
  54051. CLASS="function"
  54052. >array_diff_assoc()</B
  54053. ></A
  54054. >,
  54055.      <A
  54056. HREF="#function.array-diff-uassoc"
  54057. ><B
  54058. CLASS="function"
  54059. >array_diff_uassoc()</B
  54060. ></A
  54061. >,
  54062.      <A
  54063. HREF="#function.array-udiff-assoc"
  54064. ><B
  54065. CLASS="function"
  54066. >array_udiff_assoc()</B
  54067. ></A
  54068. >,
  54069.      <A
  54070. HREF="#function.array-udiff-uassoc"
  54071. ><B
  54072. CLASS="function"
  54073. >array_udiff_uassoc()</B
  54074. ></A
  54075. >,
  54076.      <A
  54077. HREF="#function.array-diff-key"
  54078. ><B
  54079. CLASS="function"
  54080. >array_diff_key()</B
  54081. ></A
  54082. >,
  54083.      <A
  54084. HREF="#function.array-diff-ukey"
  54085. ><B
  54086. CLASS="function"
  54087. >array_diff_ukey()</B
  54088. ></A
  54089. >,
  54090.      <A
  54091. HREF="#function.array-intersect"
  54092. ><B
  54093. CLASS="function"
  54094. >array_intersect()</B
  54095. ></A
  54096. >,
  54097.      <A
  54098. HREF="#function.array-intersect-assoc"
  54099. ><B
  54100. CLASS="function"
  54101. >array_intersect_assoc()</B
  54102. ></A
  54103. >,
  54104.      <A
  54105. HREF="#function.array-intersect-uassoc"
  54106. ><B
  54107. CLASS="function"
  54108. >array_intersect_uassoc()</B
  54109. ></A
  54110. > and
  54111.      <A
  54112. HREF="#function.array-intersect-ukey"
  54113. ><B
  54114. CLASS="function"
  54115. >array_intersect_ukey()</B
  54116. ></A
  54117. >.
  54118.     </P
  54119. ></DIV
  54120. ><H1
  54121. ><A
  54122. NAME="function.array-intersect-uassoc"
  54123. ></A
  54124. >array_intersect_uassoc</H1
  54125. ><DIV
  54126. CLASS="refnamediv"
  54127. ><A
  54128. NAME="AEN9329"
  54129. ></A
  54130. ><P
  54131. >    (PHP 5)</P
  54132. >array_intersect_uassoc -- Computes the intersection of arrays with additional index check, compares indexes by a callback function</DIV
  54133. ><DIV
  54134. CLASS="refsect1"
  54135. ><A
  54136. NAME="AEN9332"
  54137. ></A
  54138. ><H2
  54139. >Description</H2
  54140. >array <B
  54141. CLASS="methodname"
  54142. >array_intersect_uassoc</B
  54143. > ( array array1, array array2 [, array ..., callback key_compare_func])<BR
  54144. ></BR
  54145. ><P
  54146. >      <B
  54147. CLASS="function"
  54148. >array_intersect_uassoc()</B
  54149. > returns an array
  54150.      containing all the values of <VAR
  54151. CLASS="parameter"
  54152. >array1</VAR
  54153. >
  54154.      that are present in all the arguments. Note that the keys are used in
  54155.      the comparison unlike in <A
  54156. HREF="#function.array-intersect"
  54157. ><B
  54158. CLASS="function"
  54159. >array_intersect()</B
  54160. ></A
  54161. >.
  54162.     </P
  54163. ><P
  54164. >      The index comparison is done by a user supplied callback function.
  54165.      It must return an integer less than, equal to, or greater than zero
  54166.      if the first argument is considered to be respectively less than,
  54167.      equal to, or greater than the second.
  54168.     </P
  54169. ><P
  54170. >      <TABLE
  54171. WIDTH="100%"
  54172. BORDER="0"
  54173. CELLPADDING="0"
  54174. CELLSPACING="0"
  54175. CLASS="EXAMPLE"
  54176. ><TR
  54177. ><TD
  54178. ><DIV
  54179. CLASS="example"
  54180. ><A
  54181. NAME="AEN9355"
  54182. ></A
  54183. ><P
  54184. ><B
  54185. >Example 1. <B
  54186. CLASS="function"
  54187. >array_intersect_uassoc()</B
  54188. > example</B
  54189. ></P
  54190. ><TABLE
  54191. BORDER="0"
  54192. BGCOLOR="#E0E0E0"
  54193. CELLPADDING="5"
  54194. ><TR
  54195. ><TD
  54196. ><PRE
  54197. CLASS="php"
  54198. ><?php
  54199. $array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
  54200. $array2 = array("a" => "GREEN", "B" => "brown", "yellow", "red");
  54201.  
  54202. print_r(array_intersect_uassoc($array1, $array2, "strcasecmp"));
  54203. ?></PRE
  54204. ></TD
  54205. ></TR
  54206. ></TABLE
  54207. ><P
  54208. >The above example will output:</P
  54209. ><TABLE
  54210. BORDER="0"
  54211. BGCOLOR="#E0E0E0"
  54212. CELLPADDING="5"
  54213. ><TR
  54214. ><TD
  54215. ><PRE
  54216. CLASS="screen"
  54217. >Array
  54218. (
  54219.     [b] => brown
  54220. )</PRE
  54221. ></TD
  54222. ></TR
  54223. ></TABLE
  54224. ></DIV
  54225. ></TD
  54226. ></TR
  54227. ></TABLE
  54228. >
  54229.     </P
  54230. ><P
  54231. >      See also <A
  54232. HREF="#function.array-intersect"
  54233. ><B
  54234. CLASS="function"
  54235. >array_intersect()</B
  54236. ></A
  54237. >,
  54238.      <A
  54239. HREF="#function.array-intersect-assoc"
  54240. ><B
  54241. CLASS="function"
  54242. >array_intersect_assoc()</B
  54243. ></A
  54244. >,
  54245.      <A
  54246. HREF="#function.array-uintersect-assoc"
  54247. ><B
  54248. CLASS="function"
  54249. >array_uintersect_assoc()</B
  54250. ></A
  54251. >,
  54252.      <A
  54253. HREF="#function.array-uintersect-uassoc"
  54254. ><B
  54255. CLASS="function"
  54256. >array_uintersect_uassoc()</B
  54257. ></A
  54258. >,
  54259.      <A
  54260. HREF="#function.array-intersect-key"
  54261. ><B
  54262. CLASS="function"
  54263. >array_intersect_key()</B
  54264. ></A
  54265. > and
  54266.      <A
  54267. HREF="#function.array-intersect-ukey"
  54268. ><B
  54269. CLASS="function"
  54270. >array_intersect_ukey()</B
  54271. ></A
  54272. >.
  54273.     </P
  54274. ></DIV
  54275. ><H1
  54276. ><A
  54277. NAME="function.array-intersect-ukey"
  54278. ></A
  54279. >array_intersect_ukey</H1
  54280. ><DIV
  54281. CLASS="refnamediv"
  54282. ><A
  54283. NAME="AEN9369"
  54284. ></A
  54285. ><P
  54286. >    (no version information, might be only in CVS)</P
  54287. >array_intersect_ukey -- Computes the intersection of arrays using a callback function on the keys for comparison</DIV
  54288. ><DIV
  54289. CLASS="refsect1"
  54290. ><A
  54291. NAME="AEN9372"
  54292. ></A
  54293. ><H2
  54294. >Description</H2
  54295. >array <B
  54296. CLASS="methodname"
  54297. >array_intersect_ukey</B
  54298. > ( array array1, array array2 [, array ..., callback key_compare_func])<BR
  54299. ></BR
  54300. ><P
  54301. >      <B
  54302. CLASS="function"
  54303. >array_intersect_ukey()</B
  54304. > returns an array
  54305.      containing all the values of <VAR
  54306. CLASS="parameter"
  54307. >array1</VAR
  54308. >
  54309.      which have matching keys that are present in all the arguments.
  54310.     </P
  54311. ><P
  54312. >      This comparison is done by a user supplied callback function.
  54313.      It must return an integer less than, equal to, or greater than zero if the
  54314.      first key is considered to be respectively less than, equal to, or
  54315.      greater than the second.
  54316.     </P
  54317. ><P
  54318. >      <TABLE
  54319. WIDTH="100%"
  54320. BORDER="0"
  54321. CELLPADDING="0"
  54322. CELLSPACING="0"
  54323. CLASS="EXAMPLE"
  54324. ><TR
  54325. ><TD
  54326. ><DIV
  54327. CLASS="example"
  54328. ><A
  54329. NAME="AEN9394"
  54330. ></A
  54331. ><P
  54332. ><B
  54333. >Example 1. <B
  54334. CLASS="function"
  54335. >array_intersect_ukey()</B
  54336. > example</B
  54337. ></P
  54338. ><TABLE
  54339. BORDER="0"
  54340. BGCOLOR="#E0E0E0"
  54341. CELLPADDING="5"
  54342. ><TR
  54343. ><TD
  54344. ><PRE
  54345. CLASS="php"
  54346. ><?php
  54347. function key_compare_func($key1, $key2)
  54348. {
  54349.     if ($key1 == $key2)
  54350.         return 0;
  54351.     else if ($key1 > $key2)
  54352.         return 1;
  54353.     else
  54354.         return -1;
  54355. }
  54356.  
  54357. $array1 = array('blue'  => 1, 'red'  => 2, 'green'  => 3, 'purple' => 4);
  54358. $array2 = array('green' => 5, 'blue' => 6, 'yellow' => 7, 'cyan'   => 8);
  54359.  
  54360. var_dump(array_intersect_ukey($array1, $array2, 'key_compare_func'));
  54361. ?></PRE
  54362. ></TD
  54363. ></TR
  54364. ></TABLE
  54365. ><P
  54366. >The above example will output:</P
  54367. ><TABLE
  54368. BORDER="0"
  54369. BGCOLOR="#E0E0E0"
  54370. CELLPADDING="5"
  54371. ><TR
  54372. ><TD
  54373. ><PRE
  54374. CLASS="screen"
  54375. >array(2) {
  54376.   ["blue"]=>
  54377.   int(1)
  54378.   ["green"]=>
  54379.   int(3)
  54380. })</PRE
  54381. ></TD
  54382. ></TR
  54383. ></TABLE
  54384. ></DIV
  54385. ></TD
  54386. ></TR
  54387. ></TABLE
  54388. >
  54389.     </P
  54390. ><P
  54391. >      In our example you see that only the keys <VAR
  54392. CLASS="literal"
  54393. >'blue'</VAR
  54394. >
  54395.      and <VAR
  54396. CLASS="literal"
  54397. >'green'</VAR
  54398. > are present in both arrays and thus
  54399.      returned. Also notice that the values for the keys
  54400.      <VAR
  54401. CLASS="literal"
  54402. >'blue'</VAR
  54403. > and <VAR
  54404. CLASS="literal"
  54405. >'green'</VAR
  54406. > differ between
  54407.      the two arrays. A match still occurs because only the keys are checked.
  54408.      The values returned are those of <VAR
  54409. CLASS="parameter"
  54410. >array1</VAR
  54411. >.
  54412.     </P
  54413. ><P
  54414. >      The two keys from the <VAR
  54415. CLASS="literal"
  54416. >key => value</VAR
  54417. > pairs are
  54418.      considered equal only if 
  54419.      <VAR
  54420. CLASS="literal"
  54421. >(string) $key1 === (string) $key2 </VAR
  54422. >. In other words
  54423.      a strict type check is executed so the string representation must be
  54424.      the same.
  54425.     </P
  54426. ><P
  54427. >      See also <A
  54428. HREF="#function.array-diff"
  54429. ><B
  54430. CLASS="function"
  54431. >array_diff()</B
  54432. ></A
  54433. >,
  54434.      <A
  54435. HREF="#function.array-udiff"
  54436. ><B
  54437. CLASS="function"
  54438. >array_udiff()</B
  54439. ></A
  54440. >
  54441.      <A
  54442. HREF="#function.array-diff-assoc"
  54443. ><B
  54444. CLASS="function"
  54445. >array_diff_assoc()</B
  54446. ></A
  54447. >,
  54448.      <A
  54449. HREF="#function.array-diff-uassoc"
  54450. ><B
  54451. CLASS="function"
  54452. >array_diff_uassoc()</B
  54453. ></A
  54454. >,
  54455.      <A
  54456. HREF="#function.array-udiff-assoc"
  54457. ><B
  54458. CLASS="function"
  54459. >array_udiff_assoc()</B
  54460. ></A
  54461. >,
  54462.      <A
  54463. HREF="#function.array-udiff-uassoc"
  54464. ><B
  54465. CLASS="function"
  54466. >array_udiff_uassoc()</B
  54467. ></A
  54468. >,
  54469.      <A
  54470. HREF="#function.array-diff-key"
  54471. ><B
  54472. CLASS="function"
  54473. >array_diff_key()</B
  54474. ></A
  54475. >,
  54476.      <A
  54477. HREF="#function.array-diff-ukey"
  54478. ><B
  54479. CLASS="function"
  54480. >array_diff_ukey()</B
  54481. ></A
  54482. >,
  54483.      <A
  54484. HREF="#function.array-intersect"
  54485. ><B
  54486. CLASS="function"
  54487. >array_intersect()</B
  54488. ></A
  54489. >,
  54490.      <A
  54491. HREF="#function.array-intersect-assoc"
  54492. ><B
  54493. CLASS="function"
  54494. >array_intersect_assoc()</B
  54495. ></A
  54496. >,
  54497.      <A
  54498. HREF="#function.array-intersect-uassoc"
  54499. ><B
  54500. CLASS="function"
  54501. >array_intersect_uassoc()</B
  54502. ></A
  54503. > and
  54504.      <A
  54505. HREF="#function.array-intersect-key"
  54506. ><B
  54507. CLASS="function"
  54508. >array_intersect_key()</B
  54509. ></A
  54510. >.
  54511.     </P
  54512. ></DIV
  54513. ><H1
  54514. ><A
  54515. NAME="function.array-intersect"
  54516. ></A
  54517. >array_intersect</H1
  54518. ><DIV
  54519. CLASS="refnamediv"
  54520. ><A
  54521. NAME="AEN9423"
  54522. ></A
  54523. ><P
  54524. >    (PHP 4 >= 4.0.1, PHP 5)</P
  54525. >array_intersect -- Computes the intersection of arrays</DIV
  54526. ><DIV
  54527. CLASS="refsect1"
  54528. ><A
  54529. NAME="AEN9426"
  54530. ></A
  54531. ><H2
  54532. >Description</H2
  54533. >array <B
  54534. CLASS="methodname"
  54535. >array_intersect</B
  54536. > ( array array1, array array2 [, array ...])<BR
  54537. ></BR
  54538. ><P
  54539. >      <B
  54540. CLASS="function"
  54541. >array_intersect()</B
  54542. > returns an array
  54543.      containing all the values of <VAR
  54544. CLASS="parameter"
  54545. >array1</VAR
  54546. >
  54547.      that are present in all the arguments.
  54548.      Note that keys are preserved.
  54549.     </P
  54550. ><P
  54551. >      <TABLE
  54552. WIDTH="100%"
  54553. BORDER="0"
  54554. CELLPADDING="0"
  54555. CELLSPACING="0"
  54556. CLASS="EXAMPLE"
  54557. ><TR
  54558. ><TD
  54559. ><DIV
  54560. CLASS="example"
  54561. ><A
  54562. NAME="AEN9444"
  54563. ></A
  54564. ><P
  54565. ><B
  54566. >Example 1. <B
  54567. CLASS="function"
  54568. >array_intersect()</B
  54569. > example</B
  54570. ></P
  54571. ><TABLE
  54572. BORDER="0"
  54573. BGCOLOR="#E0E0E0"
  54574. CELLPADDING="5"
  54575. ><TR
  54576. ><TD
  54577. ><PRE
  54578. CLASS="php"
  54579. ><?php
  54580. $array1 = array("a" => "green", "red", "blue");
  54581. $array2 = array("b" => "green", "yellow", "red");
  54582. $result = array_intersect($array1, $array2);
  54583. ?></PRE
  54584. ></TD
  54585. ></TR
  54586. ></TABLE
  54587. ><P
  54588. >        This makes <VAR
  54589. CLASS="varname"
  54590. >$result</VAR
  54591. > have
  54592.       </P
  54593. ><TABLE
  54594. BORDER="0"
  54595. BGCOLOR="#E0E0E0"
  54596. CELLPADDING="5"
  54597. ><TR
  54598. ><TD
  54599. ><PRE
  54600. CLASS="php"
  54601. >Array
  54602. (
  54603.     [a] => green
  54604.     [0] => red
  54605. )</PRE
  54606. ></TD
  54607. ></TR
  54608. ></TABLE
  54609. ></DIV
  54610. ></TD
  54611. ></TR
  54612. ></TABLE
  54613. >
  54614.     </P
  54615. ><DIV
  54616. CLASS="note"
  54617. ><BLOCKQUOTE
  54618. CLASS="note"
  54619. ><P
  54620. ><B
  54621. >Note: </B
  54622. >
  54623.       Two elements are considered equal if and only if
  54624.       <VAR
  54625. CLASS="literal"
  54626. >(string) $elem1 === (string) $elem2</VAR
  54627. >. In words:
  54628.       when the string representation is the same.
  54629.       
  54630.      </P
  54631. ></BLOCKQUOTE
  54632. ></DIV
  54633. ><P
  54634. >      See also <A
  54635. HREF="#function.array-intersect-assoc"
  54636. ><B
  54637. CLASS="function"
  54638. >array_intersect_assoc()</B
  54639. ></A
  54640. >,
  54641.      <A
  54642. HREF="#function.array-diff"
  54643. ><B
  54644. CLASS="function"
  54645. >array_diff()</B
  54646. ></A
  54647. >, and
  54648.      <A
  54649. HREF="#function.array-diff-assoc"
  54650. ><B
  54651. CLASS="function"
  54652. >array_diff_assoc()</B
  54653. ></A
  54654. >.
  54655.     </P
  54656. ></DIV
  54657. ><H1
  54658. ><A
  54659. NAME="function.array-key-exists"
  54660. ></A
  54661. >array_key_exists</H1
  54662. ><DIV
  54663. CLASS="refnamediv"
  54664. ><A
  54665. NAME="AEN9459"
  54666. ></A
  54667. ><P
  54668. >    (PHP 4 >= 4.1.0, PHP 5)</P
  54669. >array_key_exists -- Checks if the given key or index exists in the array</DIV
  54670. ><DIV
  54671. CLASS="refsect1"
  54672. ><A
  54673. NAME="AEN9462"
  54674. ></A
  54675. ><H2
  54676. >Description</H2
  54677. >bool <B
  54678. CLASS="methodname"
  54679. >array_key_exists</B
  54680. > ( mixed key, array search)<BR
  54681. ></BR
  54682. ><P
  54683. >      <B
  54684. CLASS="function"
  54685. >array_key_exists()</B
  54686. > returns <TT
  54687. CLASS="constant"
  54688. ><B
  54689. >TRUE</B
  54690. ></TT
  54691. > if the
  54692.      given <VAR
  54693. CLASS="parameter"
  54694. >key</VAR
  54695. > is set in the array.
  54696.      <VAR
  54697. CLASS="parameter"
  54698. >key</VAR
  54699. > can be any value possible
  54700.      for an array index. <B
  54701. CLASS="function"
  54702. >array_key_exists()</B
  54703. > also works
  54704.      on objects.
  54705.     </P
  54706. ><P
  54707. >      <TABLE
  54708. WIDTH="100%"
  54709. BORDER="0"
  54710. CELLPADDING="0"
  54711. CELLSPACING="0"
  54712. CLASS="EXAMPLE"
  54713. ><TR
  54714. ><TD
  54715. ><DIV
  54716. CLASS="example"
  54717. ><A
  54718. NAME="AEN9480"
  54719. ></A
  54720. ><P
  54721. ><B
  54722. >Example 1. <B
  54723. CLASS="function"
  54724. >array_key_exists()</B
  54725. > example</B
  54726. ></P
  54727. ><TABLE
  54728. BORDER="0"
  54729. BGCOLOR="#E0E0E0"
  54730. CELLPADDING="5"
  54731. ><TR
  54732. ><TD
  54733. ><PRE
  54734. CLASS="php"
  54735. ><?php
  54736. $search_array = array('first' => 1, 'second' => 4);
  54737. if (array_key_exists('first', $search_array)) {
  54738.     echo "The 'first' element is in the array";
  54739. }
  54740. ?></PRE
  54741. ></TD
  54742. ></TR
  54743. ></TABLE
  54744. ></DIV
  54745. ></TD
  54746. ></TR
  54747. ></TABLE
  54748. >
  54749.     </P
  54750. ><DIV
  54751. CLASS="note"
  54752. ><BLOCKQUOTE
  54753. CLASS="note"
  54754. ><P
  54755. ><B
  54756. >Note: </B
  54757. >
  54758.       The name of this function is <B
  54759. CLASS="function"
  54760. >key_exists()</B
  54761. >
  54762.       in PHP 4.0.6.
  54763.      </P
  54764. ></BLOCKQUOTE
  54765. ></DIV
  54766. ><TABLE
  54767. WIDTH="100%"
  54768. BORDER="0"
  54769. CELLPADDING="0"
  54770. CELLSPACING="0"
  54771. CLASS="EXAMPLE"
  54772. ><TR
  54773. ><TD
  54774. ><DIV
  54775. CLASS="example"
  54776. ><A
  54777. NAME="AEN9487"
  54778. ></A
  54779. ><P
  54780. ><B
  54781. >Example 2. <B
  54782. CLASS="function"
  54783. >array_key_exists()</B
  54784. > vs <A
  54785. HREF="#function.isset"
  54786. ><B
  54787. CLASS="function"
  54788. >isset()</B
  54789. ></A
  54790. ></B
  54791. ></P
  54792. ><P
  54793. >       <A
  54794. HREF="#function.isset"
  54795. ><B
  54796. CLASS="function"
  54797. >isset()</B
  54798. ></A
  54799. > does not return <TT
  54800. CLASS="constant"
  54801. ><B
  54802. >TRUE</B
  54803. ></TT
  54804. > for array keys
  54805.       that correspond to a <TT
  54806. CLASS="constant"
  54807. ><B
  54808. >NULL</B
  54809. ></TT
  54810. > value, while
  54811.       <B
  54812. CLASS="function"
  54813. >array_key_exists()</B
  54814. > does.
  54815.      </P
  54816. ><TABLE
  54817. BORDER="0"
  54818. BGCOLOR="#E0E0E0"
  54819. CELLPADDING="5"
  54820. ><TR
  54821. ><TD
  54822. ><PRE
  54823. CLASS="php"
  54824. ><?php
  54825. $search_array = array('first' => null, 'second' => 4);
  54826.  
  54827. // returns false
  54828. isset($search_array['first']);
  54829.  
  54830. // returns true
  54831. array_key_exists('first', $search_array);
  54832. ?></PRE
  54833. ></TD
  54834. ></TR
  54835. ></TABLE
  54836. ></DIV
  54837. ></TD
  54838. ></TR
  54839. ></TABLE
  54840. ><P
  54841. >      See also <A
  54842. HREF="#function.isset"
  54843. ><B
  54844. CLASS="function"
  54845. >isset()</B
  54846. ></A
  54847. >, 
  54848.      <A
  54849. HREF="#function.array-keys"
  54850. ><B
  54851. CLASS="function"
  54852. >array_keys()</B
  54853. ></A
  54854. >, and
  54855.      <A
  54856. HREF="#function.in-array"
  54857. ><B
  54858. CLASS="function"
  54859. >in_array()</B
  54860. ></A
  54861. >.
  54862.     </P
  54863. ></DIV
  54864. ><H1
  54865. ><A
  54866. NAME="function.array-keys"
  54867. ></A
  54868. >array_keys</H1
  54869. ><DIV
  54870. CLASS="refnamediv"
  54871. ><A
  54872. NAME="AEN9502"
  54873. ></A
  54874. ><P
  54875. >    (PHP 4 , PHP 5)</P
  54876. >array_keys -- Return all the keys of an array</DIV
  54877. ><DIV
  54878. CLASS="refsect1"
  54879. ><A
  54880. NAME="AEN9505"
  54881. ></A
  54882. ><H2
  54883. >Description</H2
  54884. >array <B
  54885. CLASS="methodname"
  54886. >array_keys</B
  54887. > ( array input [, mixed search_value [, bool strict]])<BR
  54888. ></BR
  54889. ><P
  54890. >      <B
  54891. CLASS="function"
  54892. >array_keys()</B
  54893. > returns the keys, numeric and
  54894.      string, from the <VAR
  54895. CLASS="parameter"
  54896. >input</VAR
  54897. > array.
  54898.     </P
  54899. ><P
  54900. >      If the optional <VAR
  54901. CLASS="parameter"
  54902. >search_value</VAR
  54903. > is specified,
  54904.      then only the keys for that value are returned. Otherwise, all
  54905.      the keys from the <VAR
  54906. CLASS="parameter"
  54907. >input</VAR
  54908. > are returned.
  54909.      As of PHP 5, you can use <VAR
  54910. CLASS="parameter"
  54911. >strict</VAR
  54912. > parameter for
  54913.      comparison including type (===).
  54914.     </P
  54915. ><P
  54916. >      <TABLE
  54917. WIDTH="100%"
  54918. BORDER="0"
  54919. CELLPADDING="0"
  54920. CELLSPACING="0"
  54921. CLASS="EXAMPLE"
  54922. ><TR
  54923. ><TD
  54924. ><DIV
  54925. CLASS="example"
  54926. ><A
  54927. NAME="AEN9527"
  54928. ></A
  54929. ><P
  54930. ><B
  54931. >Example 1. <B
  54932. CLASS="function"
  54933. >array_keys()</B
  54934. > example</B
  54935. ></P
  54936. ><TABLE
  54937. BORDER="0"
  54938. BGCOLOR="#E0E0E0"
  54939. CELLPADDING="5"
  54940. ><TR
  54941. ><TD
  54942. ><PRE
  54943. CLASS="php"
  54944. ><?php
  54945. $array = array(0 => 100, "color" => "red");
  54946. print_r(array_keys($array));
  54947.  
  54948. $array = array("blue", "red", "green", "blue", "blue");
  54949. print_r(array_keys($array, "blue"));
  54950.  
  54951. $array = array("color" => array("blue", "red", "green"),
  54952.                "size"  => array("small", "medium", "large"));
  54953. print_r(array_keys($array));
  54954. ?></PRE
  54955. ></TD
  54956. ></TR
  54957. ></TABLE
  54958. ><P
  54959. >The above example will output:</P
  54960. ><TABLE
  54961. BORDER="0"
  54962. BGCOLOR="#E0E0E0"
  54963. CELLPADDING="5"
  54964. ><TR
  54965. ><TD
  54966. ><PRE
  54967. CLASS="screen"
  54968. >Array
  54969. (
  54970.     [0] => 0
  54971.     [1] => color
  54972. )
  54973. Array
  54974. (
  54975.     [0] => 0
  54976.     [1] => 3
  54977.     [2] => 4
  54978. )
  54979. Array
  54980. (
  54981.     [0] => color
  54982.     [1] => size
  54983. )</PRE
  54984. ></TD
  54985. ></TR
  54986. ></TABLE
  54987. ></DIV
  54988. ></TD
  54989. ></TR
  54990. ></TABLE
  54991. >
  54992.     </P
  54993. ><P
  54994. >      See also <A
  54995. HREF="#function.array-values"
  54996. ><B
  54997. CLASS="function"
  54998. >array_values()</B
  54999. ></A
  55000. > and
  55001.      <A
  55002. HREF="#function.array-key-exists"
  55003. ><B
  55004. CLASS="function"
  55005. >array_key_exists()</B
  55006. ></A
  55007. >.
  55008.     </P
  55009. ></DIV
  55010. ><H1
  55011. ><A
  55012. NAME="function.array-map"
  55013. ></A
  55014. >array_map</H1
  55015. ><DIV
  55016. CLASS="refnamediv"
  55017. ><A
  55018. NAME="AEN9537"
  55019. ></A
  55020. ><P
  55021. >    (PHP 4 >= 4.0.6, PHP 5)</P
  55022. >array_map -- 
  55023.      Applies the callback to the elements of the given arrays
  55024.     </DIV
  55025. ><DIV
  55026. CLASS="refsect1"
  55027. ><A
  55028. NAME="AEN9540"
  55029. ></A
  55030. ><H2
  55031. >Description</H2
  55032. >array <B
  55033. CLASS="methodname"
  55034. >array_map</B
  55035. > ( callback callback, array arr1 [, array ...])<BR
  55036. ></BR
  55037. ><P
  55038. >      <B
  55039. CLASS="function"
  55040. >array_map()</B
  55041. > returns an array containing all
  55042.      the elements of <VAR
  55043. CLASS="parameter"
  55044. >arr1</VAR
  55045. > after applying the
  55046.      <VAR
  55047. CLASS="parameter"
  55048. >callback</VAR
  55049. > function to each one.
  55050.      The number of parameters that the <VAR
  55051. CLASS="parameter"
  55052. >callback</VAR
  55053. >
  55054.      function accepts
  55055.      should match the number of arrays
  55056.      passed to the <B
  55057. CLASS="function"
  55058. >array_map()</B
  55059. >
  55060.     </P
  55061. ><P
  55062. >      <TABLE
  55063. WIDTH="100%"
  55064. BORDER="0"
  55065. CELLPADDING="0"
  55066. CELLSPACING="0"
  55067. CLASS="EXAMPLE"
  55068. ><TR
  55069. ><TD
  55070. ><DIV
  55071. CLASS="example"
  55072. ><A
  55073. NAME="AEN9561"
  55074. ></A
  55075. ><P
  55076. ><B
  55077. >Example 1. <B
  55078. CLASS="function"
  55079. >array_map()</B
  55080. > example</B
  55081. ></P
  55082. ><TABLE
  55083. BORDER="0"
  55084. BGCOLOR="#E0E0E0"
  55085. CELLPADDING="5"
  55086. ><TR
  55087. ><TD
  55088. ><PRE
  55089. CLASS="php"
  55090. ><?php
  55091. function cube($n) 
  55092. {
  55093.     return($n * $n * $n);
  55094. }
  55095.  
  55096. $a = array(1, 2, 3, 4, 5);
  55097. $b = array_map("cube", $a);
  55098. print_r($b);
  55099. ?></PRE
  55100. ></TD
  55101. ></TR
  55102. ></TABLE
  55103. ><P
  55104. >        This makes <VAR
  55105. CLASS="varname"
  55106. >$b</VAR
  55107. > have:
  55108.       </P
  55109. ><TABLE
  55110. BORDER="0"
  55111. BGCOLOR="#E0E0E0"
  55112. CELLPADDING="5"
  55113. ><TR
  55114. ><TD
  55115. ><PRE
  55116. CLASS="screen"
  55117. >Array
  55118. (
  55119.     [0] => 1
  55120.     [1] => 8
  55121.     [2] => 27
  55122.     [3] => 64
  55123.     [4] => 125
  55124. )</PRE
  55125. ></TD
  55126. ></TR
  55127. ></TABLE
  55128. ></DIV
  55129. ></TD
  55130. ></TR
  55131. ></TABLE
  55132. >
  55133.     </P
  55134. ><P
  55135. >      <TABLE
  55136. WIDTH="100%"
  55137. BORDER="0"
  55138. CELLPADDING="0"
  55139. CELLSPACING="0"
  55140. CLASS="EXAMPLE"
  55141. ><TR
  55142. ><TD
  55143. ><DIV
  55144. CLASS="example"
  55145. ><A
  55146. NAME="AEN9569"
  55147. ></A
  55148. ><P
  55149. ><B
  55150. >Example 2. <B
  55151. CLASS="function"
  55152. >array_map()</B
  55153. > - using more arrays</B
  55154. ></P
  55155. ><TABLE
  55156. BORDER="0"
  55157. BGCOLOR="#E0E0E0"
  55158. CELLPADDING="5"
  55159. ><TR
  55160. ><TD
  55161. ><PRE
  55162. CLASS="php"
  55163. ><?php
  55164. function show_Spanish($n, $m) 
  55165. {
  55166.     return("The number $n is called $m in Spanish");
  55167. }
  55168.  
  55169. function map_Spanish($n, $m) 
  55170. {
  55171.     return(array($n => $m));
  55172. }
  55173.  
  55174. $a = array(1, 2, 3, 4, 5);
  55175. $b = array("uno", "dos", "tres", "cuatro", "cinco");
  55176.  
  55177. $c = array_map("show_Spanish", $a, $b);
  55178. print_r($c);
  55179.  
  55180. $d = array_map("map_Spanish", $a , $b);
  55181. print_r($d);
  55182. ?></PRE
  55183. ></TD
  55184. ></TR
  55185. ></TABLE
  55186. ><P
  55187. >The above example will output:</P
  55188. ><TABLE
  55189. BORDER="0"
  55190. BGCOLOR="#E0E0E0"
  55191. CELLPADDING="5"
  55192. ><TR
  55193. ><TD
  55194. ><PRE
  55195. CLASS="screen"
  55196. >// printout of $c
  55197. Array
  55198. (
  55199.     [0] => The number 1 is called uno in Spanish
  55200.     [1] => The number 2 is called dos in Spanish
  55201.     [2] => The number 3 is called tres in Spanish
  55202.     [3] => The number 4 is called cuatro in Spanish
  55203.     [4] => The number 5 is called cinco in Spanish
  55204. )
  55205.  
  55206. // printout of $d
  55207. Array
  55208. (
  55209.     [0] => Array
  55210.         (
  55211.             [1] => uno
  55212.         )
  55213.  
  55214.     [1] => Array
  55215.         (
  55216.             [2] => dos
  55217.         )
  55218.  
  55219.     [2] => Array
  55220.         (
  55221.             [3] => tres
  55222.         )
  55223.  
  55224.     [3] => Array
  55225.         (
  55226.             [4] => cuatro
  55227.         )
  55228.  
  55229.     [4] => Array
  55230.         (
  55231.             [5] => cinco
  55232.         )
  55233.  
  55234. )</PRE
  55235. ></TD
  55236. ></TR
  55237. ></TABLE
  55238. ></DIV
  55239. ></TD
  55240. ></TR
  55241. ></TABLE
  55242. >
  55243.     </P
  55244. ><P
  55245. >      Usually when using two or more arrays, they should be of equal length
  55246.      because the callback function is applied in parallel to the corresponding
  55247.      elements.
  55248.      If the arrays are of unequal length, the shortest one will be extended
  55249.      with empty elements.
  55250.     </P
  55251. ><P
  55252. >      An interesting use of this function is to construct an array of arrays,
  55253.      which can be easily performed by using <TT
  55254. CLASS="constant"
  55255. ><B
  55256. >NULL</B
  55257. ></TT
  55258. >
  55259.      as the name of the callback function
  55260.     </P
  55261. ><P
  55262. >      <TABLE
  55263. WIDTH="100%"
  55264. BORDER="0"
  55265. CELLPADDING="0"
  55266. CELLSPACING="0"
  55267. CLASS="EXAMPLE"
  55268. ><TR
  55269. ><TD
  55270. ><DIV
  55271. CLASS="example"
  55272. ><A
  55273. NAME="AEN9579"
  55274. ></A
  55275. ><P
  55276. ><B
  55277. >Example 3. Creating an array of arrays</B
  55278. ></P
  55279. ><TABLE
  55280. BORDER="0"
  55281. BGCOLOR="#E0E0E0"
  55282. CELLPADDING="5"
  55283. ><TR
  55284. ><TD
  55285. ><PRE
  55286. CLASS="php"
  55287. ><?php
  55288. $a = array(1, 2, 3, 4, 5);
  55289. $b = array("one", "two", "three", "four", "five");
  55290. $c = array("uno", "dos", "tres", "cuatro", "cinco");
  55291.  
  55292. $d = array_map(null, $a, $b, $c);
  55293. print_r($d);
  55294. ?></PRE
  55295. ></TD
  55296. ></TR
  55297. ></TABLE
  55298. ><P
  55299. >The above example will output:</P
  55300. ><TABLE
  55301. BORDER="0"
  55302. BGCOLOR="#E0E0E0"
  55303. CELLPADDING="5"
  55304. ><TR
  55305. ><TD
  55306. ><PRE
  55307. CLASS="screen"
  55308. >Array
  55309. (
  55310.     [0] => Array
  55311.         (
  55312.             [0] => 1
  55313.             [1] => one
  55314.             [2] => uno
  55315.         )
  55316.  
  55317.     [1] => Array
  55318.         (
  55319.             [0] => 2
  55320.             [1] => two
  55321.             [2] => dos
  55322.         )
  55323.  
  55324.     [2] => Array
  55325.         (
  55326.             [0] => 3
  55327.             [1] => three
  55328.             [2] => tres
  55329.         )
  55330.  
  55331.     [3] => Array
  55332.         (
  55333.             [0] => 4
  55334.             [1] => four
  55335.             [2] => cuatro
  55336.         )
  55337.  
  55338.     [4] => Array
  55339.         (
  55340.             [0] => 5
  55341.             [1] => five
  55342.             [2] => cinco
  55343.         )
  55344.  
  55345. )</PRE
  55346. ></TD
  55347. ></TR
  55348. ></TABLE
  55349. ></DIV
  55350. ></TD
  55351. ></TR
  55352. ></TABLE
  55353. >
  55354.     </P
  55355. ><P
  55356. >      See also <A
  55357. HREF="#function.array-filter"
  55358. ><B
  55359. CLASS="function"
  55360. >array_filter()</B
  55361. ></A
  55362. >, 
  55363.      <A
  55364. HREF="#function.array-reduce"
  55365. ><B
  55366. CLASS="function"
  55367. >array_reduce()</B
  55368. ></A
  55369. >, and
  55370.      <A
  55371. HREF="#function.array-walk"
  55372. ><B
  55373. CLASS="function"
  55374. >array_walk()</B
  55375. ></A
  55376. >.
  55377.     </P
  55378. ></DIV
  55379. ><H1
  55380. ><A
  55381. NAME="function.array-merge-recursive"
  55382. ></A
  55383. >array_merge_recursive</H1
  55384. ><DIV
  55385. CLASS="refnamediv"
  55386. ><A
  55387. NAME="AEN9589"
  55388. ></A
  55389. ><P
  55390. >    (PHP 4 >= 4.0.1, PHP 5)</P
  55391. >array_merge_recursive -- Merge two or more arrays recursively</DIV
  55392. ><DIV
  55393. CLASS="refsect1"
  55394. ><A
  55395. NAME="AEN9592"
  55396. ></A
  55397. ><H2
  55398. >Description</H2
  55399. >array <B
  55400. CLASS="methodname"
  55401. >array_merge_recursive</B
  55402. > ( array array1, array array2 [, array ...])<BR
  55403. ></BR
  55404. ><P
  55405. >      <B
  55406. CLASS="function"
  55407. >array_merge_recursive()</B
  55408. > merges the elements of
  55409.      two or more arrays together so that the values of one are appended
  55410.      to the end of the previous one.  It returns the resulting array.
  55411.     </P
  55412. ><P
  55413. >      If the input arrays have the same string keys, then the values for
  55414.      these keys are merged together into an array, and this is done
  55415.      recursively, so that if one of the values is an array itself, the
  55416.      function will merge it with a corresponding entry in another array
  55417.      too. If, however, the arrays have the same numeric key, the later
  55418.      value will not overwrite the original value, but will be appended.
  55419.     </P
  55420. ><P
  55421. >      <TABLE
  55422. WIDTH="100%"
  55423. BORDER="0"
  55424. CELLPADDING="0"
  55425. CELLSPACING="0"
  55426. CLASS="EXAMPLE"
  55427. ><TR
  55428. ><TD
  55429. ><DIV
  55430. CLASS="example"
  55431. ><A
  55432. NAME="AEN9610"
  55433. ></A
  55434. ><P
  55435. ><B
  55436. >Example 1. <B
  55437. CLASS="function"
  55438. >array_merge_recursive()</B
  55439. > example</B
  55440. ></P
  55441. ><TABLE
  55442. BORDER="0"
  55443. BGCOLOR="#E0E0E0"
  55444. CELLPADDING="5"
  55445. ><TR
  55446. ><TD
  55447. ><PRE
  55448. CLASS="php"
  55449. ><?php
  55450. $ar1 = array("color" => array("favorite" => "red"), 5);
  55451. $ar2 = array(10, "color" => array("favorite" => "green", "blue"));
  55452. $result = array_merge_recursive($ar1, $ar2);
  55453. ?></PRE
  55454. ></TD
  55455. ></TR
  55456. ></TABLE
  55457. ><P
  55458. >        The <VAR
  55459. CLASS="literal"
  55460. >$result</VAR
  55461. > will be:
  55462.       </P
  55463. ><TABLE
  55464. BORDER="0"
  55465. BGCOLOR="#E0E0E0"
  55466. CELLPADDING="5"
  55467. ><TR
  55468. ><TD
  55469. ><PRE
  55470. CLASS="php"
  55471. >Array
  55472. (
  55473.     [color] => Array
  55474.         (
  55475.             [favorite] => Array
  55476.                 (
  55477.                     [0] => red
  55478.                     [1] => green
  55479.                 )
  55480.  
  55481.             [0] => blue
  55482.         )
  55483.  
  55484.     [0] => 5
  55485.     [1] => 10
  55486. )</PRE
  55487. ></TD
  55488. ></TR
  55489. ></TABLE
  55490. ></DIV
  55491. ></TD
  55492. ></TR
  55493. ></TABLE
  55494. >
  55495.     </P
  55496. ><P
  55497. >      See also <A
  55498. HREF="#function.array-merge"
  55499. ><B
  55500. CLASS="function"
  55501. >array_merge()</B
  55502. ></A
  55503. >.
  55504.     </P
  55505. ></DIV
  55506. ><H1
  55507. ><A
  55508. NAME="function.array-merge"
  55509. ></A
  55510. >array_merge</H1
  55511. ><DIV
  55512. CLASS="refnamediv"
  55513. ><A
  55514. NAME="AEN9620"
  55515. ></A
  55516. ><P
  55517. >    (PHP 4 , PHP 5)</P
  55518. >array_merge -- Merge one or more arrays</DIV
  55519. ><DIV
  55520. CLASS="refsect1"
  55521. ><A
  55522. NAME="AEN9623"
  55523. ></A
  55524. ><H2
  55525. >Description</H2
  55526. >array <B
  55527. CLASS="methodname"
  55528. >array_merge</B
  55529. > ( array array1 [, array array2 [, array ...]])<BR
  55530. ></BR
  55531. ><P
  55532. >      <B
  55533. CLASS="function"
  55534. >array_merge()</B
  55535. > merges the elements of one or
  55536.      more arrays together so that the values of one are appended to
  55537.      the end of the previous one.  It returns the resulting array.
  55538.     </P
  55539. ><P
  55540. >      If the input arrays have the same string keys, then the later value for
  55541.      that key will overwrite the previous one.  If, however, the arrays
  55542.      contain numeric keys, the later value will <SPAN
  55543. CLASS="strong"
  55544. ><B
  55545. CLASS="emphasis"
  55546. >not</B
  55547. ></SPAN
  55548. > overwrite the original value, but will be
  55549.      appended.
  55550.     </P
  55551. ><P
  55552. >      If only one array is given and the array is numerically indexed, the
  55553.      keys get reindexed in a continuous way. For associative arrays, duplicate
  55554.      entries will be merged into the last one. See example three for details.
  55555.     </P
  55556. ><P
  55557. >      <TABLE
  55558. WIDTH="100%"
  55559. BORDER="0"
  55560. CELLPADDING="0"
  55561. CELLSPACING="0"
  55562. CLASS="EXAMPLE"
  55563. ><TR
  55564. ><TD
  55565. ><DIV
  55566. CLASS="example"
  55567. ><A
  55568. NAME="AEN9643"
  55569. ></A
  55570. ><P
  55571. ><B
  55572. >Example 1. <B
  55573. CLASS="function"
  55574. >array_merge()</B
  55575. > example</B
  55576. ></P
  55577. ><TABLE
  55578. BORDER="0"
  55579. BGCOLOR="#E0E0E0"
  55580. CELLPADDING="5"
  55581. ><TR
  55582. ><TD
  55583. ><PRE
  55584. CLASS="php"
  55585. ><?php
  55586. $array1 = array("color" => "red", 2, 4);
  55587. $array2 = array("a", "b", "color" => "green", "shape" => "trapezoid", 4);
  55588. $result = array_merge($array1, $array2);
  55589. print_r($result);
  55590. ?></PRE
  55591. ></TD
  55592. ></TR
  55593. ></TABLE
  55594. ><P
  55595. >        The <VAR
  55596. CLASS="varname"
  55597. >$result</VAR
  55598. > is:
  55599.       </P
  55600. ><TABLE
  55601. BORDER="0"
  55602. BGCOLOR="#E0E0E0"
  55603. CELLPADDING="5"
  55604. ><TR
  55605. ><TD
  55606. ><PRE
  55607. CLASS="php"
  55608. >Array
  55609. (
  55610.     [color] => green
  55611.     [0] => 2
  55612.     [1] => 4
  55613.     [2] => a
  55614.     [3] => b
  55615.     [shape] => trapezoid
  55616.     [4] => 4
  55617. )</PRE
  55618. ></TD
  55619. ></TR
  55620. ></TABLE
  55621. ></DIV
  55622. ></TD
  55623. ></TR
  55624. ></TABLE
  55625. >
  55626.     </P
  55627. ><P
  55628. >      <TABLE
  55629. WIDTH="100%"
  55630. BORDER="0"
  55631. CELLPADDING="0"
  55632. CELLSPACING="0"
  55633. CLASS="EXAMPLE"
  55634. ><TR
  55635. ><TD
  55636. ><DIV
  55637. CLASS="example"
  55638. ><A
  55639. NAME="AEN9651"
  55640. ></A
  55641. ><P
  55642. ><B
  55643. >Example 2. Simple <B
  55644. CLASS="function"
  55645. >array_merge()</B
  55646. > example</B
  55647. ></P
  55648. ><TABLE
  55649. BORDER="0"
  55650. BGCOLOR="#E0E0E0"
  55651. CELLPADDING="5"
  55652. ><TR
  55653. ><TD
  55654. ><PRE
  55655. CLASS="php"
  55656. ><?php
  55657. $array1 = array();
  55658. $array2 = array(1 => "data");
  55659. $result = array_merge($array1, $array2);
  55660. ?></PRE
  55661. ></TD
  55662. ></TR
  55663. ></TABLE
  55664. ><P
  55665. >        Don't forget that numeric keys will be renumbered!
  55666.       </P
  55667. ><TABLE
  55668. BORDER="0"
  55669. BGCOLOR="#E0E0E0"
  55670. CELLPADDING="5"
  55671. ><TR
  55672. ><TD
  55673. ><PRE
  55674. CLASS="php"
  55675. >Array
  55676. (
  55677.     [0] => data
  55678. )</PRE
  55679. ></TD
  55680. ></TR
  55681. ></TABLE
  55682. ><P
  55683. >        If you want to completely preserve the arrays and just want to append
  55684.        them to each other, use the <VAR
  55685. CLASS="literal"
  55686. >+</VAR
  55687. > operator:
  55688.       </P
  55689. ><TABLE
  55690. BORDER="0"
  55691. BGCOLOR="#E0E0E0"
  55692. CELLPADDING="5"
  55693. ><TR
  55694. ><TD
  55695. ><PRE
  55696. CLASS="php"
  55697. ><?php
  55698. $array1 = array();
  55699. $array2 = array(1 => "data");
  55700. $result = $array1 + $array2;
  55701. ?></PRE
  55702. ></TD
  55703. ></TR
  55704. ></TABLE
  55705. ><P
  55706. >        The numeric key will be preserved and thus the association remains.
  55707.       </P
  55708. ><TABLE
  55709. BORDER="0"
  55710. BGCOLOR="#E0E0E0"
  55711. CELLPADDING="5"
  55712. ><TR
  55713. ><TD
  55714. ><PRE
  55715. CLASS="php"
  55716. >Array
  55717. (
  55718.     [1] => data
  55719. )</PRE
  55720. ></TD
  55721. ></TR
  55722. ></TABLE
  55723. ></DIV
  55724. ></TD
  55725. ></TR
  55726. ></TABLE
  55727. >
  55728.      <TABLE
  55729. WIDTH="100%"
  55730. BORDER="0"
  55731. CELLPADDING="0"
  55732. CELLSPACING="0"
  55733. CLASS="EXAMPLE"
  55734. ><TR
  55735. ><TD
  55736. ><DIV
  55737. CLASS="example"
  55738. ><A
  55739. NAME="AEN9662"
  55740. ></A
  55741. ><P
  55742. ><B
  55743. >Example 3. <B
  55744. CLASS="function"
  55745. >array_merge()</B
  55746. > example</B
  55747. ></P
  55748. ><TABLE
  55749. BORDER="0"
  55750. BGCOLOR="#E0E0E0"
  55751. CELLPADDING="5"
  55752. ><TR
  55753. ><TD
  55754. ><PRE
  55755. CLASS="php"
  55756. ><?php
  55757. $array_one = array(0 => "jay", 1 => "bob", 2 => "randal", 3 => "dante");
  55758. $array_two = array("jay" => "bob", "randal" => "dante", "jay" => "jason");
  55759.  
  55760. unset($array_one[2]);
  55761.  
  55762. $result_one = array_merge($array_one);
  55763. $result_two = array_merge($array_two);
  55764.  
  55765. print_r($result_one);
  55766. print_r($result_two);
  55767. ?></PRE
  55768. ></TD
  55769. ></TR
  55770. ></TABLE
  55771. ><P
  55772. >The above example will output:</P
  55773. ><TABLE
  55774. BORDER="0"
  55775. BGCOLOR="#E0E0E0"
  55776. CELLPADDING="5"
  55777. ><TR
  55778. ><TD
  55779. ><PRE
  55780. CLASS="php"
  55781. >Array
  55782. (
  55783.     [0] => jay
  55784.     [1] => bob
  55785.     [2] => dante
  55786. )
  55787. Array
  55788. (
  55789.     [jay] => jason
  55790.     [randal] => dante
  55791. )</PRE
  55792. ></TD
  55793. ></TR
  55794. ></TABLE
  55795. ></DIV
  55796. ></TD
  55797. ></TR
  55798. ></TABLE
  55799. >
  55800.     </P
  55801. ><DIV
  55802. CLASS="note"
  55803. ><BLOCKQUOTE
  55804. CLASS="note"
  55805. ><P
  55806. ><B
  55807. >Note: </B
  55808. >
  55809.       Shared keys will be overwritten on a first-come first-served basis.
  55810.      </P
  55811. ></BLOCKQUOTE
  55812. ></DIV
  55813. ><DIV
  55814. CLASS="warning"
  55815. ><P
  55816. ></P
  55817. ><TABLE
  55818. CLASS="warning"
  55819. BORDER="1"
  55820. WIDTH="100%"
  55821. ><TR
  55822. ><TD
  55823. ALIGN="CENTER"
  55824. ><B
  55825. >Warning</B
  55826. ></TD
  55827. ></TR
  55828. ><TR
  55829. ><TD
  55830. ALIGN="LEFT"
  55831. ><P
  55832. >       The behavior of <B
  55833. CLASS="function"
  55834. >array_merge()</B
  55835. > was modified in PHP 5. Unlike PHP 4, <B
  55836. CLASS="function"
  55837. >array_merge()</B
  55838. > 
  55839.       now only accepts parameters of type <A
  55840. HREF="#language.types.array"
  55841. ><B
  55842. CLASS="type"
  55843. >array</B
  55844. ></A
  55845. >. However, you can use typecasting 
  55846.       to merge other types. See the example below for details.
  55847.      </P
  55848. ><P
  55849. >       <TABLE
  55850. WIDTH="100%"
  55851. BORDER="0"
  55852. CELLPADDING="0"
  55853. CELLSPACING="0"
  55854. CLASS="EXAMPLE"
  55855. ><TR
  55856. ><TD
  55857. ><DIV
  55858. CLASS="example"
  55859. ><A
  55860. NAME="AEN9676"
  55861. ></A
  55862. ><P
  55863. ><B
  55864. >Example 4. <B
  55865. CLASS="function"
  55866. >array_merge()</B
  55867. > PHP 5 example</B
  55868. ></P
  55869. ><TABLE
  55870. BORDER="0"
  55871. BGCOLOR="#E0E0E0"
  55872. CELLPADDING="5"
  55873. ><TR
  55874. ><TD
  55875. ><PRE
  55876. CLASS="php"
  55877. ><?php
  55878. $beginning = 'foo';
  55879. $end = array(1 => 'bar');
  55880. $result = array_merge((array)$beginning, (array)$end);
  55881. ?></PRE
  55882. ></TD
  55883. ></TR
  55884. ></TABLE
  55885. ><P
  55886. >The above example will output:</P
  55887. ><TABLE
  55888. BORDER="0"
  55889. BGCOLOR="#E0E0E0"
  55890. CELLPADDING="5"
  55891. ><TR
  55892. ><TD
  55893. ><PRE
  55894. CLASS="php"
  55895. >Array
  55896. (
  55897.     [0] => foo
  55898.     [1] => bar
  55899. )</PRE
  55900. ></TD
  55901. ></TR
  55902. ></TABLE
  55903. ></DIV
  55904. ></TD
  55905. ></TR
  55906. ></TABLE
  55907. >
  55908.      </P
  55909. ></TD
  55910. ></TR
  55911. ></TABLE
  55912. ></DIV
  55913. ><P
  55914. >      See also <A
  55915. HREF="#function.array-merge-recursive"
  55916. ><B
  55917. CLASS="function"
  55918. >array_merge_recursive()</B
  55919. ></A
  55920. >,
  55921.      <A
  55922. HREF="#function.array-combine"
  55923. ><B
  55924. CLASS="function"
  55925. >array_combine()</B
  55926. ></A
  55927. > and
  55928.      <A
  55929. HREF="#language.operators.array"
  55930. >array operators</A
  55931. >.
  55932.     </P
  55933. ></DIV
  55934. ><H1
  55935. ><A
  55936. NAME="function.array-multisort"
  55937. ></A
  55938. >array_multisort</H1
  55939. ><DIV
  55940. CLASS="refnamediv"
  55941. ><A
  55942. NAME="AEN9687"
  55943. ></A
  55944. ><P
  55945. >    (PHP 4 , PHP 5)</P
  55946. >array_multisort -- Sort multiple or multi-dimensional arrays</DIV
  55947. ><DIV
  55948. CLASS="refsect1"
  55949. ><A
  55950. NAME="AEN9690"
  55951. ></A
  55952. ><H2
  55953. >Description</H2
  55954. >bool <B
  55955. CLASS="methodname"
  55956. >array_multisort</B
  55957. > ( array ar1 [, mixed arg [, mixed ... [, array ...]]])<BR
  55958. ></BR
  55959. ><P
  55960. >      Returns <TT
  55961. CLASS="constant"
  55962. ><B
  55963. >TRUE</B
  55964. ></TT
  55965. > on success or <TT
  55966. CLASS="constant"
  55967. ><B
  55968. >FALSE</B
  55969. ></TT
  55970. > on failure.
  55971.     </P
  55972. ><P
  55973. >      <B
  55974. CLASS="function"
  55975. >array_multisort()</B
  55976. > can be used to sort several
  55977.      arrays at once, or a multi-dimensional array by one or more
  55978.      dimensions.
  55979.     </P
  55980. ><P
  55981. >      Associative (<A
  55982. HREF="#language.types.string"
  55983. ><B
  55984. CLASS="type"
  55985. >string</B
  55986. ></A
  55987. >) keys will be maintained, but numeric
  55988.      keys will be re-indexed.
  55989.     </P
  55990. ><P
  55991. >      The input arrays are treated as columns of a table to be sorted
  55992.      by rows - this resembles the functionality of SQL ORDER BY
  55993.      clause. The first array is the primary one to sort by. The rows
  55994.      (values) in that array that compare the same are sorted by the
  55995.      next input array, and so on.
  55996.     </P
  55997. ><P
  55998. >      The argument structure of this function is a bit unusual, but
  55999.      flexible. The first argument has to be an array. Subsequently,
  56000.      each argument can be either an array or a sorting flag from the
  56001.      following lists.
  56002.     </P
  56003. ><P
  56004. >      Sorting order flags:
  56005.      <P
  56006. ></P
  56007. ><UL
  56008. ><LI
  56009. ><P
  56010. ><TT
  56011. CLASS="constant"
  56012. ><B
  56013. >SORT_ASC</B
  56014. ></TT
  56015. > - Sort in ascending order</P
  56016. ></LI
  56017. ><LI
  56018. ><P
  56019. ><TT
  56020. CLASS="constant"
  56021. ><B
  56022. >SORT_DESC</B
  56023. ></TT
  56024. > - Sort in descending order</P
  56025. ></LI
  56026. ></UL
  56027. >
  56028.     </P
  56029. ><P
  56030. >      Sorting type flags:
  56031.      <P
  56032. ></P
  56033. ><UL
  56034. ><LI
  56035. ><P
  56036. ><TT
  56037. CLASS="constant"
  56038. ><B
  56039. >SORT_REGULAR</B
  56040. ></TT
  56041. > - Compare items normally</P
  56042. ></LI
  56043. ><LI
  56044. ><P
  56045. ><TT
  56046. CLASS="constant"
  56047. ><B
  56048. >SORT_NUMERIC</B
  56049. ></TT
  56050. > - Compare items numerically</P
  56051. ></LI
  56052. ><LI
  56053. ><P
  56054. ><TT
  56055. CLASS="constant"
  56056. ><B
  56057. >SORT_STRING</B
  56058. ></TT
  56059. > - Compare items as strings</P
  56060. ></LI
  56061. ></UL
  56062. >
  56063.     </P
  56064. ><P
  56065. >      No two sorting flags of the same type can be specified after each
  56066.      array. The sorting flags specified after an array argument apply
  56067.      only to that array - they are reset to default <TT
  56068. CLASS="constant"
  56069. ><B
  56070. >SORT_ASC</B
  56071. ></TT
  56072. > and
  56073.      <TT
  56074. CLASS="constant"
  56075. ><B
  56076. >SORT_REGULAR</B
  56077. ></TT
  56078. > before each new array argument.
  56079.     </P
  56080. ><P
  56081. >      <TABLE
  56082. WIDTH="100%"
  56083. BORDER="0"
  56084. CELLPADDING="0"
  56085. CELLSPACING="0"
  56086. CLASS="EXAMPLE"
  56087. ><TR
  56088. ><TD
  56089. ><DIV
  56090. CLASS="example"
  56091. ><A
  56092. NAME="AEN9739"
  56093. ></A
  56094. ><P
  56095. ><B
  56096. >Example 1. Sorting multiple arrays</B
  56097. ></P
  56098. ><TABLE
  56099. BORDER="0"
  56100. BGCOLOR="#E0E0E0"
  56101. CELLPADDING="5"
  56102. ><TR
  56103. ><TD
  56104. ><PRE
  56105. CLASS="php"
  56106. ><?php
  56107. $ar1 = array("10", 100, 100, "a");
  56108. $ar2 = array(1, 3, "2", 1);
  56109. array_multisort($ar1, $ar2);
  56110.  
  56111. var_dump($ar1);
  56112. var_dump($ar2);
  56113. ?></PRE
  56114. ></TD
  56115. ></TR
  56116. ></TABLE
  56117. ><P
  56118. >        In this example, after sorting, the first array will contain "10",
  56119.        "a", 100, 100. The second array will contain 1, 1, "2", 3. The
  56120.        entries in the second array corresponding to the identical
  56121.        entries in the first array (100 and 100) were sorted as well.
  56122.       </P
  56123. ><TABLE
  56124. BORDER="0"
  56125. BGCOLOR="#E0E0E0"
  56126. CELLPADDING="5"
  56127. ><TR
  56128. ><TD
  56129. ><PRE
  56130. CLASS="screen"
  56131. >array(4) {
  56132.   [0]=> string(2) "10"
  56133.   [1]=> string(1) "a"
  56134.   [2]=> int(100)
  56135.   [3]=> int(100)
  56136. }
  56137. array(4) {
  56138.   [0]=> int(1)
  56139.   [1]=> int(1)
  56140.   [2]=> string(1) "2"
  56141.   [3]=> int(3)
  56142. }</PRE
  56143. ></TD
  56144. ></TR
  56145. ></TABLE
  56146. ></DIV
  56147. ></TD
  56148. ></TR
  56149. ></TABLE
  56150. >
  56151.     </P
  56152. ><P
  56153. >      <TABLE
  56154. WIDTH="100%"
  56155. BORDER="0"
  56156. CELLPADDING="0"
  56157. CELLSPACING="0"
  56158. CLASS="EXAMPLE"
  56159. ><TR
  56160. ><TD
  56161. ><DIV
  56162. CLASS="example"
  56163. ><A
  56164. NAME="AEN9745"
  56165. ></A
  56166. ><P
  56167. ><B
  56168. >Example 2. Sorting multi-dimensional array</B
  56169. ></P
  56170. ><TABLE
  56171. BORDER="0"
  56172. BGCOLOR="#E0E0E0"
  56173. CELLPADDING="5"
  56174. ><TR
  56175. ><TD
  56176. ><PRE
  56177. CLASS="php"
  56178. ><?php
  56179. $ar = array(array("10", 100, 100, "a"), array(1, 3, "2", 1));
  56180. array_multisort($ar[0], SORT_ASC, SORT_STRING,
  56181.                 $ar[1], SORT_NUMERIC, SORT_DESC);
  56182. ?></PRE
  56183. ></TD
  56184. ></TR
  56185. ></TABLE
  56186. ><P
  56187. >        In this example, after sorting, the first array will contain "10",
  56188.        100, 100, "a" (it was sorted as strings in ascending order). The
  56189.        second will contain 1, 3, "2", 1 (sorted as numbers, in
  56190.        descending order).
  56191.       </P
  56192. ><TABLE
  56193. BORDER="0"
  56194. BGCOLOR="#E0E0E0"
  56195. CELLPADDING="5"
  56196. ><TR
  56197. ><TD
  56198. ><PRE
  56199. CLASS="screen"
  56200. >array(2) {
  56201.   [0]=> array(4) {
  56202.     [0]=> string(2) "10"
  56203.     [1]=> int(100)
  56204.     [2]=> int(100)
  56205.     [3]=> string(1) "a"
  56206.   }
  56207.   [1]=> array(4) {
  56208.     [0]=> int(1)
  56209.     [1]=> int(3)
  56210.     [2]=> string(1) "2"
  56211.     [3]=> int(1)
  56212.   }
  56213. }</PRE
  56214. ></TD
  56215. ></TR
  56216. ></TABLE
  56217. ></DIV
  56218. ></TD
  56219. ></TR
  56220. ></TABLE
  56221. >
  56222.     </P
  56223. ><P
  56224. >      <TABLE
  56225. WIDTH="100%"
  56226. BORDER="0"
  56227. CELLPADDING="0"
  56228. CELLSPACING="0"
  56229. CLASS="EXAMPLE"
  56230. ><TR
  56231. ><TD
  56232. ><DIV
  56233. CLASS="example"
  56234. ><A
  56235. NAME="AEN9751"
  56236. ></A
  56237. ><P
  56238. ><B
  56239. >Example 3. Sorting database results</B
  56240. ></P
  56241. ><P
  56242. >        For this example, each element in the <VAR
  56243. CLASS="varname"
  56244. >data</VAR
  56245. >
  56246.        array represents one row in a table. This type of dataset is typical
  56247.        of database records.
  56248.       </P
  56249. ><P
  56250. >        Example data:
  56251.       </P
  56252. ><TABLE
  56253. BORDER="0"
  56254. BGCOLOR="#E0E0E0"
  56255. CELLPADDING="5"
  56256. ><TR
  56257. ><TD
  56258. ><PRE
  56259. CLASS="screen"
  56260. >volume | edition
  56261. -------+--------
  56262.     67 |       2
  56263.     86 |       1
  56264.     85 |       6
  56265.     98 |       2
  56266.     86 |       6
  56267.     67 |       7</PRE
  56268. ></TD
  56269. ></TR
  56270. ></TABLE
  56271. ><P
  56272. >        The data as an array, called <VAR
  56273. CLASS="varname"
  56274. >data</VAR
  56275. >. This would usually,
  56276.        for example, be obtained by looping with <A
  56277. HREF="#function.mysql-fetch-assoc"
  56278. ><B
  56279. CLASS="function"
  56280. >mysql_fetch_assoc()</B
  56281. ></A
  56282. >.
  56283.       </P
  56284. ><TABLE
  56285. BORDER="0"
  56286. BGCOLOR="#E0E0E0"
  56287. CELLPADDING="5"
  56288. ><TR
  56289. ><TD
  56290. ><PRE
  56291. CLASS="php"
  56292. ><?php
  56293. $data[] = array('volume' => 67, 'edition' => 2);
  56294. $data[] = array('volume' => 86, 'edition' => 1);
  56295. $data[] = array('volume' => 85, 'edition' => 6);
  56296. $data[] = array('volume' => 98, 'edition' => 2);
  56297. $data[] = array('volume' => 86, 'edition' => 6);
  56298. $data[] = array('volume' => 67, 'edition' => 7);
  56299. ?></PRE
  56300. ></TD
  56301. ></TR
  56302. ></TABLE
  56303. ><P
  56304. >        In this example, we will order by <VAR
  56305. CLASS="varname"
  56306. >volume</VAR
  56307. > descending,
  56308.        <VAR
  56309. CLASS="varname"
  56310. >edition</VAR
  56311. > ascending.
  56312.       </P
  56313. ><P
  56314. >        We have an array of rows, but <B
  56315. CLASS="function"
  56316. >array_multisort()</B
  56317. >
  56318.        requires an array of columns, so we use the the below code to obtain the
  56319.        columns, then perform the sorting.
  56320.       </P
  56321. ><TABLE
  56322. BORDER="0"
  56323. BGCOLOR="#E0E0E0"
  56324. CELLPADDING="5"
  56325. ><TR
  56326. ><TD
  56327. ><PRE
  56328. CLASS="php"
  56329. ><?php
  56330. // Obtain a list of columns
  56331. foreach ($data as $key => $row) {
  56332.     $volume[$key]  = $row['volume'];
  56333.     $edition[$key] = $row['edition'];
  56334. }
  56335.  
  56336. // Sort the data with volume descending, edition ascending
  56337. // Add $data as the last parameter, to sort by the common key
  56338. array_multisort($volume, SORT_DESC, $edition, SORT_ASC, $data);
  56339. ?></PRE
  56340. ></TD
  56341. ></TR
  56342. ></TABLE
  56343. ><P
  56344. >        The dataset is now sorted, and will look like this:
  56345.       </P
  56346. ><TABLE
  56347. BORDER="0"
  56348. BGCOLOR="#E0E0E0"
  56349. CELLPADDING="5"
  56350. ><TR
  56351. ><TD
  56352. ><PRE
  56353. CLASS="screen"
  56354. >volume | edition
  56355. -------+--------
  56356.     98 |       2
  56357.     86 |       1
  56358.     86 |       6
  56359.     85 |       6
  56360.     67 |       2
  56361.     67 |       7</PRE
  56362. ></TD
  56363. ></TR
  56364. ></TABLE
  56365. ></DIV
  56366. ></TD
  56367. ></TR
  56368. ></TABLE
  56369. >
  56370.     </P
  56371. ><P
  56372. >      <TABLE
  56373. WIDTH="100%"
  56374. BORDER="0"
  56375. CELLPADDING="0"
  56376. CELLSPACING="0"
  56377. CLASS="EXAMPLE"
  56378. ><TR
  56379. ><TD
  56380. ><DIV
  56381. CLASS="example"
  56382. ><A
  56383. NAME="AEN9770"
  56384. ></A
  56385. ><P
  56386. ><B
  56387. >Example 4. Case insensitive sorting</B
  56388. ></P
  56389. ><P
  56390. >        Both <TT
  56391. CLASS="constant"
  56392. ><B
  56393. >SORT_STRING</B
  56394. ></TT
  56395. > and
  56396.        <TT
  56397. CLASS="constant"
  56398. ><B
  56399. >SORT_REGULAR</B
  56400. ></TT
  56401. > are case sensitive, strings
  56402.        starting with a capital letter will come before strings starting
  56403.        with a lowercase letter.
  56404.       </P
  56405. ><P
  56406. >        To perform a case insensitve search, force the sorting order to be
  56407.        determined by a lowercase copy of the original array.
  56408.       </P
  56409. ><TABLE
  56410. BORDER="0"
  56411. BGCOLOR="#E0E0E0"
  56412. CELLPADDING="5"
  56413. ><TR
  56414. ><TD
  56415. ><PRE
  56416. CLASS="php"
  56417. ><?php
  56418. $array = array('Alpha', 'atomic', 'Beta', 'bank');
  56419. $array_lowercase = array_map('strtolower', $array);
  56420.  
  56421. array_multisort($array_lowercase, SORT_ASC, SORT_STRING, $array);
  56422.  
  56423. print_r($array);
  56424. ?></PRE
  56425. ></TD
  56426. ></TR
  56427. ></TABLE
  56428. ><P
  56429. >The above example will output:</P
  56430. ><TABLE
  56431. BORDER="0"
  56432. BGCOLOR="#E0E0E0"
  56433. CELLPADDING="5"
  56434. ><TR
  56435. ><TD
  56436. ><PRE
  56437. CLASS="screen"
  56438. >Array
  56439. (
  56440.     [0] => Alpha
  56441.     [1] => atomic
  56442.     [2] => bank
  56443.     [3] => Beta
  56444. )</PRE
  56445. ></TD
  56446. ></TR
  56447. ></TABLE
  56448. ></DIV
  56449. ></TD
  56450. ></TR
  56451. ></TABLE
  56452. >
  56453.     </P
  56454. ></DIV
  56455. ><H1
  56456. ><A
  56457. NAME="function.array-pad"
  56458. ></A
  56459. >array_pad</H1
  56460. ><DIV
  56461. CLASS="refnamediv"
  56462. ><A
  56463. NAME="AEN9780"
  56464. ></A
  56465. ><P
  56466. >    (PHP 4 , PHP 5)</P
  56467. >array_pad -- 
  56468.      Pad array to the specified length with a value
  56469.     </DIV
  56470. ><DIV
  56471. CLASS="refsect1"
  56472. ><A
  56473. NAME="AEN9783"
  56474. ></A
  56475. ><H2
  56476. >Description</H2
  56477. >array <B
  56478. CLASS="methodname"
  56479. >array_pad</B
  56480. > ( array input, int pad_size, mixed pad_value)<BR
  56481. ></BR
  56482. ><P
  56483. >      <B
  56484. CLASS="function"
  56485. >array_pad()</B
  56486. > returns a copy of the
  56487.      <VAR
  56488. CLASS="parameter"
  56489. >input</VAR
  56490. > padded to size specified by
  56491.      <VAR
  56492. CLASS="parameter"
  56493. >pad_size</VAR
  56494. > with value
  56495.      <VAR
  56496. CLASS="parameter"
  56497. >pad_value</VAR
  56498. >. If
  56499.      <VAR
  56500. CLASS="parameter"
  56501. >pad_size</VAR
  56502. > is positive then the array is
  56503.      padded on the right, if it's negative then on the left. If the
  56504.      absolute value of <VAR
  56505. CLASS="parameter"
  56506. >pad_size</VAR
  56507. > is less than or
  56508.      equal to the length of the <VAR
  56509. CLASS="parameter"
  56510. >input</VAR
  56511. > then no
  56512.      padding takes place.
  56513.     </P
  56514. ><P
  56515. >      <TABLE
  56516. WIDTH="100%"
  56517. BORDER="0"
  56518. CELLPADDING="0"
  56519. CELLSPACING="0"
  56520. CLASS="EXAMPLE"
  56521. ><TR
  56522. ><TD
  56523. ><DIV
  56524. CLASS="example"
  56525. ><A
  56526. NAME="AEN9806"
  56527. ></A
  56528. ><P
  56529. ><B
  56530. >Example 1. <B
  56531. CLASS="function"
  56532. >array_pad()</B
  56533. > example</B
  56534. ></P
  56535. ><TABLE
  56536. BORDER="0"
  56537. BGCOLOR="#E0E0E0"
  56538. CELLPADDING="5"
  56539. ><TR
  56540. ><TD
  56541. ><PRE
  56542. CLASS="php"
  56543. ><?php
  56544. $input = array(12, 10, 9);
  56545.  
  56546. $result = array_pad($input, 5, 0);
  56547. // result is array(12, 10, 9, 0, 0)
  56548.  
  56549. $result = array_pad($input, -7, -1);
  56550. // result is array(-1, -1, -1, -1, 12, 10, 9)
  56551.  
  56552. $result = array_pad($input, 2, "noop");
  56553. // not padded
  56554. ?></PRE
  56555. ></TD
  56556. ></TR
  56557. ></TABLE
  56558. ></DIV
  56559. ></TD
  56560. ></TR
  56561. ></TABLE
  56562. >
  56563.     </P
  56564. ><P
  56565. >      See also <A
  56566. HREF="#function.array-fill"
  56567. ><B
  56568. CLASS="function"
  56569. >array_fill()</B
  56570. ></A
  56571. > and
  56572.      <A
  56573. HREF="#function.range"
  56574. ><B
  56575. CLASS="function"
  56576. >range()</B
  56577. ></A
  56578. >.
  56579.     </P
  56580. ></DIV
  56581. ><H1
  56582. ><A
  56583. NAME="function.array-pop"
  56584. ></A
  56585. >array_pop</H1
  56586. ><DIV
  56587. CLASS="refnamediv"
  56588. ><A
  56589. NAME="AEN9814"
  56590. ></A
  56591. ><P
  56592. >    (PHP 4 , PHP 5)</P
  56593. >array_pop -- Pop the element off the end of array</DIV
  56594. ><DIV
  56595. CLASS="refsect1"
  56596. ><A
  56597. NAME="AEN9817"
  56598. ></A
  56599. ><H2
  56600. >Description</H2
  56601. >mixed <B
  56602. CLASS="methodname"
  56603. >array_pop</B
  56604. > ( array &array)<BR
  56605. ></BR
  56606. ><P
  56607. >      <B
  56608. CLASS="function"
  56609. >array_pop()</B
  56610. > pops and returns the last value of
  56611.      the <VAR
  56612. CLASS="parameter"
  56613. >array</VAR
  56614. >, shortening the
  56615.      <VAR
  56616. CLASS="parameter"
  56617. >array</VAR
  56618. > by one element.
  56619.      If <VAR
  56620. CLASS="parameter"
  56621. >array</VAR
  56622. > is empty (or is not an array),
  56623.      <TT
  56624. CLASS="constant"
  56625. ><B
  56626. >NULL</B
  56627. ></TT
  56628. > will be returned.
  56629.     </P
  56630. ><DIV
  56631. CLASS="note"
  56632. ><BLOCKQUOTE
  56633. CLASS="note"
  56634. ><P
  56635. ><B
  56636. >Note: </B
  56637. >This function will 
  56638. <A
  56639. HREF="#function.reset"
  56640. ><B
  56641. CLASS="function"
  56642. >reset()</B
  56643. ></A
  56644. > the <A
  56645. HREF="#language.types.array"
  56646. ><B
  56647. CLASS="type"
  56648. >array</B
  56649. ></A
  56650. > pointer after 
  56651. use.</P
  56652. ></BLOCKQUOTE
  56653. ></DIV
  56654. ><P
  56655. >      <TABLE
  56656. WIDTH="100%"
  56657. BORDER="0"
  56658. CELLPADDING="0"
  56659. CELLSPACING="0"
  56660. CLASS="EXAMPLE"
  56661. ><TR
  56662. ><TD
  56663. ><DIV
  56664. CLASS="example"
  56665. ><A
  56666. NAME="AEN9836"
  56667. ></A
  56668. ><P
  56669. ><B
  56670. >Example 1. <B
  56671. CLASS="function"
  56672. >array_pop()</B
  56673. > example</B
  56674. ></P
  56675. ><TABLE
  56676. BORDER="0"
  56677. BGCOLOR="#E0E0E0"
  56678. CELLPADDING="5"
  56679. ><TR
  56680. ><TD
  56681. ><PRE
  56682. CLASS="php"
  56683. ><?php
  56684. $stack = array("orange", "banana", "apple", "raspberry");
  56685. $fruit = array_pop($stack);
  56686. print_r($stack);
  56687. ?></PRE
  56688. ></TD
  56689. ></TR
  56690. ></TABLE
  56691. ><P
  56692. >        After this, <VAR
  56693. CLASS="varname"
  56694. >$stack</VAR
  56695. > will have only 3 elements:
  56696.       </P
  56697. ><TABLE
  56698. BORDER="0"
  56699. BGCOLOR="#E0E0E0"
  56700. CELLPADDING="5"
  56701. ><TR
  56702. ><TD
  56703. ><PRE
  56704. CLASS="php"
  56705. >Array
  56706. (
  56707.     [0] => orange
  56708.     [1] => banana
  56709.     [2] => apple
  56710. )</PRE
  56711. ></TD
  56712. ></TR
  56713. ></TABLE
  56714. ><P
  56715. >        and <VAR
  56716. CLASS="literal"
  56717. >raspberry</VAR
  56718. > will be assigned to
  56719.        <VAR
  56720. CLASS="varname"
  56721. >$fruit</VAR
  56722. >.
  56723.       </P
  56724. ></DIV
  56725. ></TD
  56726. ></TR
  56727. ></TABLE
  56728. >
  56729.     </P
  56730. ><P
  56731. >      See also <A
  56732. HREF="#function.array-push"
  56733. ><B
  56734. CLASS="function"
  56735. >array_push()</B
  56736. ></A
  56737. >,
  56738.      <A
  56739. HREF="#function.array-shift"
  56740. ><B
  56741. CLASS="function"
  56742. >array_shift()</B
  56743. ></A
  56744. >, and
  56745.      <A
  56746. HREF="#function.array-unshift"
  56747. ><B
  56748. CLASS="function"
  56749. >array_unshift()</B
  56750. ></A
  56751. >.
  56752.     </P
  56753. ></DIV
  56754. ><H1
  56755. ><A
  56756. NAME="function.array-push"
  56757. ></A
  56758. >array_push</H1
  56759. ><DIV
  56760. CLASS="refnamediv"
  56761. ><A
  56762. NAME="AEN9851"
  56763. ></A
  56764. ><P
  56765. >    (PHP 4 , PHP 5)</P
  56766. >array_push -- 
  56767.      Push one or more elements onto the end of array
  56768.     </DIV
  56769. ><DIV
  56770. CLASS="refsect1"
  56771. ><A
  56772. NAME="AEN9854"
  56773. ></A
  56774. ><H2
  56775. >Description</H2
  56776. >int <B
  56777. CLASS="methodname"
  56778. >array_push</B
  56779. > ( array &array, mixed var [, mixed ...])<BR
  56780. ></BR
  56781. ><P
  56782. >      <B
  56783. CLASS="function"
  56784. >array_push()</B
  56785. > treats
  56786.      <VAR
  56787. CLASS="parameter"
  56788. >array</VAR
  56789. > as a stack, and pushes the passed
  56790.      variables onto the end of <VAR
  56791. CLASS="parameter"
  56792. >array</VAR
  56793. >. The
  56794.      length of <VAR
  56795. CLASS="parameter"
  56796. >array</VAR
  56797. > increases by the number of
  56798.      variables pushed. Has the same effect as:
  56799.      <TABLE
  56800. BORDER="0"
  56801. BGCOLOR="#E0E0E0"
  56802. CELLPADDING="5"
  56803. ><TR
  56804. ><TD
  56805. ><PRE
  56806. CLASS="php"
  56807. ><?php
  56808. $array[] = $var;
  56809. ?></PRE
  56810. ></TD
  56811. ></TR
  56812. ></TABLE
  56813. >
  56814.      repeated for each <VAR
  56815. CLASS="parameter"
  56816. >var</VAR
  56817. >.
  56818.     </P
  56819. ><P
  56820. >      Returns the new number of elements in the array.
  56821.     </P
  56822. ><P
  56823. >      <TABLE
  56824. WIDTH="100%"
  56825. BORDER="0"
  56826. CELLPADDING="0"
  56827. CELLSPACING="0"
  56828. CLASS="EXAMPLE"
  56829. ><TR
  56830. ><TD
  56831. ><DIV
  56832. CLASS="example"
  56833. ><A
  56834. NAME="AEN9877"
  56835. ></A
  56836. ><P
  56837. ><B
  56838. >Example 1. <B
  56839. CLASS="function"
  56840. >array_push()</B
  56841. > example</B
  56842. ></P
  56843. ><TABLE
  56844. BORDER="0"
  56845. BGCOLOR="#E0E0E0"
  56846. CELLPADDING="5"
  56847. ><TR
  56848. ><TD
  56849. ><PRE
  56850. CLASS="php"
  56851. ><?php
  56852. $stack = array("orange", "banana");
  56853. array_push($stack, "apple", "raspberry");
  56854. print_r($stack);
  56855. ?></PRE
  56856. ></TD
  56857. ></TR
  56858. ></TABLE
  56859. ><P
  56860. >        This example would result in <VAR
  56861. CLASS="varname"
  56862. >$stack</VAR
  56863. > having
  56864.        the following elements:
  56865.       </P
  56866. ><TABLE
  56867. BORDER="0"
  56868. BGCOLOR="#E0E0E0"
  56869. CELLPADDING="5"
  56870. ><TR
  56871. ><TD
  56872. ><PRE
  56873. CLASS="php"
  56874. >Array
  56875. (
  56876.     [0] => orange
  56877.     [1] => banana
  56878.     [2] => apple
  56879.     [3] => raspberry
  56880. )</PRE
  56881. ></TD
  56882. ></TR
  56883. ></TABLE
  56884. ></DIV
  56885. ></TD
  56886. ></TR
  56887. ></TABLE
  56888. >
  56889.     </P
  56890. ><DIV
  56891. CLASS="note"
  56892. ><BLOCKQUOTE
  56893. CLASS="note"
  56894. ><P
  56895. ><B
  56896. >Note: </B
  56897. >
  56898.       If you use <B
  56899. CLASS="function"
  56900. >array_push()</B
  56901. > to add one element to the
  56902.       array it's better to use <VAR
  56903. CLASS="literal"
  56904. >$array[] = </VAR
  56905. > because in that
  56906.       way there is no overhead of calling a function.
  56907.      </P
  56908. ></BLOCKQUOTE
  56909. ></DIV
  56910. ><P
  56911. >      See also <A
  56912. HREF="#function.array-pop"
  56913. ><B
  56914. CLASS="function"
  56915. >array_pop()</B
  56916. ></A
  56917. >,
  56918.      <A
  56919. HREF="#function.array-shift"
  56920. ><B
  56921. CLASS="function"
  56922. >array_shift()</B
  56923. ></A
  56924. >, and
  56925.      <A
  56926. HREF="#function.array-unshift"
  56927. ><B
  56928. CLASS="function"
  56929. >array_unshift()</B
  56930. ></A
  56931. >.
  56932.     </P
  56933. ></DIV
  56934. ><H1
  56935. ><A
  56936. NAME="function.array-rand"
  56937. ></A
  56938. >array_rand</H1
  56939. ><DIV
  56940. CLASS="refnamediv"
  56941. ><A
  56942. NAME="AEN9893"
  56943. ></A
  56944. ><P
  56945. >    (PHP 4 , PHP 5)</P
  56946. >array_rand -- 
  56947.      Pick one or more random entries out of an array
  56948.     </DIV
  56949. ><DIV
  56950. CLASS="refsect1"
  56951. ><A
  56952. NAME="AEN9896"
  56953. ></A
  56954. ><H2
  56955. >Description</H2
  56956. >mixed <B
  56957. CLASS="methodname"
  56958. >array_rand</B
  56959. > ( array input [, int num_req])<BR
  56960. ></BR
  56961. ><P
  56962. >      <B
  56963. CLASS="function"
  56964. >array_rand()</B
  56965. > is rather useful when you want to
  56966.      pick one or more random entries out of an array. It takes an
  56967.      <VAR
  56968. CLASS="parameter"
  56969. >input</VAR
  56970. > array and an optional argument
  56971.      <VAR
  56972. CLASS="parameter"
  56973. >num_req</VAR
  56974. > which specifies how many entries you
  56975.      want to pick - if not specified, it defaults to 1.
  56976.     </P
  56977. ><P
  56978. >      If you are picking only one entry, <B
  56979. CLASS="function"
  56980. >array_rand()</B
  56981. >
  56982.      returns the key for a random entry. Otherwise, it returns an array
  56983.      of keys for the random entries. This is done so that you can pick
  56984.      random keys as well as values out of the array.
  56985.     </P
  56986. ><DIV
  56987. CLASS="note"
  56988. ><BLOCKQUOTE
  56989. CLASS="note"
  56990. ><P
  56991. ><B
  56992. >Note: </B
  56993. >As of PHP 4.2.0, there is no need 
  56994. to seed the random number generator with <A
  56995. HREF="#function.srand"
  56996. ><B
  56997. CLASS="function"
  56998. >srand()</B
  56999. ></A
  57000. > or 
  57001. <A
  57002. HREF="#function.mt-srand"
  57003. ><B
  57004. CLASS="function"
  57005. >mt_srand()</B
  57006. ></A
  57007. > as this is now done automatically.
  57008. </P
  57009. ></BLOCKQUOTE
  57010. ></DIV
  57011. ><P
  57012. >      <TABLE
  57013. WIDTH="100%"
  57014. BORDER="0"
  57015. CELLPADDING="0"
  57016. CELLSPACING="0"
  57017. CLASS="EXAMPLE"
  57018. ><TR
  57019. ><TD
  57020. ><DIV
  57021. CLASS="example"
  57022. ><A
  57023. NAME="AEN9918"
  57024. ></A
  57025. ><P
  57026. ><B
  57027. >Example 1. <B
  57028. CLASS="function"
  57029. >array_rand()</B
  57030. > example</B
  57031. ></P
  57032. ><TABLE
  57033. BORDER="0"
  57034. BGCOLOR="#E0E0E0"
  57035. CELLPADDING="5"
  57036. ><TR
  57037. ><TD
  57038. ><PRE
  57039. CLASS="php"
  57040. ><?php
  57041. srand((float) microtime() * 10000000);
  57042. $input = array("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
  57043. $rand_keys = array_rand($input, 2);
  57044. echo $input[$rand_keys[0]] . "\n";
  57045. echo $input[$rand_keys[1]] . "\n";
  57046. ?></PRE
  57047. ></TD
  57048. ></TR
  57049. ></TABLE
  57050. ></DIV
  57051. ></TD
  57052. ></TR
  57053. ></TABLE
  57054. >
  57055.     </P
  57056. ><P
  57057. >      See also <A
  57058. HREF="#function.shuffle"
  57059. ><B
  57060. CLASS="function"
  57061. >shuffle()</B
  57062. ></A
  57063. >.
  57064.     </P
  57065. ></DIV
  57066. ><H1
  57067. ><A
  57068. NAME="function.array-reduce"
  57069. ></A
  57070. >array_reduce</H1
  57071. ><DIV
  57072. CLASS="refnamediv"
  57073. ><A
  57074. NAME="AEN9925"
  57075. ></A
  57076. ><P
  57077. >    (PHP 4 >= 4.0.5, PHP 5)</P
  57078. >array_reduce -- 
  57079.      Iteratively reduce the array to a single value using a callback
  57080.      function
  57081.     </DIV
  57082. ><DIV
  57083. CLASS="refsect1"
  57084. ><A
  57085. NAME="AEN9928"
  57086. ></A
  57087. ><H2
  57088. >Description</H2
  57089. >mixed <B
  57090. CLASS="methodname"
  57091. >array_reduce</B
  57092. > ( array input, callback function [, int initial])<BR
  57093. ></BR
  57094. ><P
  57095. >      <B
  57096. CLASS="function"
  57097. >array_reduce()</B
  57098. > applies iteratively the
  57099.      <VAR
  57100. CLASS="parameter"
  57101. >function</VAR
  57102. > function to the elements of the
  57103.      array <VAR
  57104. CLASS="parameter"
  57105. >input</VAR
  57106. >, so as to reduce the array to
  57107.      a single value. If the optional <VAR
  57108. CLASS="parameter"
  57109. >initial</VAR
  57110. > is
  57111.      available, it will be used at the beginning of the process, or as
  57112.      a final result in case the array is empty.
  57113.     </P
  57114. ><P
  57115. >      <TABLE
  57116. WIDTH="100%"
  57117. BORDER="0"
  57118. CELLPADDING="0"
  57119. CELLSPACING="0"
  57120. CLASS="EXAMPLE"
  57121. ><TR
  57122. ><TD
  57123. ><DIV
  57124. CLASS="example"
  57125. ><A
  57126. NAME="AEN9948"
  57127. ></A
  57128. ><P
  57129. ><B
  57130. >Example 1. <B
  57131. CLASS="function"
  57132. >array_reduce()</B
  57133. > example</B
  57134. ></P
  57135. ><TABLE
  57136. BORDER="0"
  57137. BGCOLOR="#E0E0E0"
  57138. CELLPADDING="5"
  57139. ><TR
  57140. ><TD
  57141. ><PRE
  57142. CLASS="php"
  57143. ><?php
  57144. function rsum($v, $w) 
  57145. {
  57146.     $v += $w;
  57147.     return $v;
  57148. }
  57149.  
  57150. function rmul($v, $w) 
  57151. {
  57152.     $v *= $w;
  57153.     return $v;
  57154. }
  57155.  
  57156. $a = array(1, 2, 3, 4, 5);
  57157. $x = array();
  57158. $b = array_reduce($a, "rsum");
  57159. $c = array_reduce($a, "rmul", 10);
  57160. $d = array_reduce($x, "rsum", 1);
  57161. ?></PRE
  57162. ></TD
  57163. ></TR
  57164. ></TABLE
  57165. ></DIV
  57166. ></TD
  57167. ></TR
  57168. ></TABLE
  57169. >
  57170.     </P
  57171. ><P
  57172. >      This will result in <VAR
  57173. CLASS="varname"
  57174. >$b</VAR
  57175. > containing
  57176.      <VAR
  57177. CLASS="literal"
  57178. >15</VAR
  57179. >, <VAR
  57180. CLASS="varname"
  57181. >$c</VAR
  57182. > containing
  57183.      <VAR
  57184. CLASS="literal"
  57185. >1200</VAR
  57186. > (= 1*2*3*4*5*10), and
  57187.      <VAR
  57188. CLASS="varname"
  57189. >$d</VAR
  57190. > containing <VAR
  57191. CLASS="literal"
  57192. >1</VAR
  57193. >.
  57194.     </P
  57195. ><P
  57196. >      See also <A
  57197. HREF="#function.array-filter"
  57198. ><B
  57199. CLASS="function"
  57200. >array_filter()</B
  57201. ></A
  57202. >,
  57203.      <A
  57204. HREF="#function.array-map"
  57205. ><B
  57206. CLASS="function"
  57207. >array_map()</B
  57208. ></A
  57209. >,
  57210.      <A
  57211. HREF="#function.array-unique"
  57212. ><B
  57213. CLASS="function"
  57214. >array_unique()</B
  57215. ></A
  57216. >, and
  57217.      <A
  57218. HREF="#function.array-count-values"
  57219. ><B
  57220. CLASS="function"
  57221. >array_count_values()</B
  57222. ></A
  57223. >.
  57224.     </P
  57225. ></DIV
  57226. ><H1
  57227. ><A
  57228. NAME="function.array-reverse"
  57229. ></A
  57230. >array_reverse</H1
  57231. ><DIV
  57232. CLASS="refnamediv"
  57233. ><A
  57234. NAME="AEN9965"
  57235. ></A
  57236. ><P
  57237. >    (PHP 4 , PHP 5)</P
  57238. >array_reverse -- 
  57239.      Return an array with elements in reverse order
  57240.     </DIV
  57241. ><DIV
  57242. CLASS="refsect1"
  57243. ><A
  57244. NAME="AEN9968"
  57245. ></A
  57246. ><H2
  57247. >Description</H2
  57248. >array <B
  57249. CLASS="methodname"
  57250. >array_reverse</B
  57251. > ( array array [, bool preserve_keys])<BR
  57252. ></BR
  57253. ><P
  57254. >      <B
  57255. CLASS="function"
  57256. >array_reverse()</B
  57257. > takes input
  57258.      <VAR
  57259. CLASS="parameter"
  57260. >array</VAR
  57261. > and returns a new array with the
  57262.      order of the elements reversed, preserving the keys if
  57263.      <VAR
  57264. CLASS="parameter"
  57265. >preserve_keys</VAR
  57266. > is <TT
  57267. CLASS="constant"
  57268. ><B
  57269. >TRUE</B
  57270. ></TT
  57271. >.
  57272.     </P
  57273. ><P
  57274. >      <TABLE
  57275. WIDTH="100%"
  57276. BORDER="0"
  57277. CELLPADDING="0"
  57278. CELLSPACING="0"
  57279. CLASS="EXAMPLE"
  57280. ><TR
  57281. ><TD
  57282. ><DIV
  57283. CLASS="example"
  57284. ><A
  57285. NAME="AEN9985"
  57286. ></A
  57287. ><P
  57288. ><B
  57289. >Example 1. <B
  57290. CLASS="function"
  57291. >array_reverse()</B
  57292. > example</B
  57293. ></P
  57294. ><TABLE
  57295. BORDER="0"
  57296. BGCOLOR="#E0E0E0"
  57297. CELLPADDING="5"
  57298. ><TR
  57299. ><TD
  57300. ><PRE
  57301. CLASS="php"
  57302. ><?php
  57303. $input  = array("php", 4.0, array("green", "red"));
  57304. $result = array_reverse($input);
  57305. $result_keyed = array_reverse($input, true);
  57306. ?></PRE
  57307. ></TD
  57308. ></TR
  57309. ></TABLE
  57310. ><P
  57311. >        This makes both <VAR
  57312. CLASS="varname"
  57313. >$result</VAR
  57314. > and
  57315.        <VAR
  57316. CLASS="varname"
  57317. >$result_keyed</VAR
  57318. > have the same elements, but
  57319.        note the difference between the keys. The printout of
  57320.        <VAR
  57321. CLASS="varname"
  57322. >$result</VAR
  57323. > and
  57324.        <VAR
  57325. CLASS="varname"
  57326. >$result_keyed</VAR
  57327. > will be:
  57328.       </P
  57329. ><TABLE
  57330. BORDER="0"
  57331. BGCOLOR="#E0E0E0"
  57332. CELLPADDING="5"
  57333. ><TR
  57334. ><TD
  57335. ><PRE
  57336. CLASS="php"
  57337. >Array
  57338. (
  57339.     [0] => Array
  57340.         (
  57341.             [0] => green
  57342.             [1] => red
  57343.         )
  57344.  
  57345.     [1] => 4
  57346.     [2] => php
  57347. )
  57348. Array
  57349. (
  57350.     [2] => Array
  57351.         (
  57352.             [0] => green
  57353.             [1] => red
  57354.         )
  57355.  
  57356.     [1] => 4
  57357.     [0] => php
  57358. )</PRE
  57359. ></TD
  57360. ></TR
  57361. ></TABLE
  57362. ></DIV
  57363. ></TD
  57364. ></TR
  57365. ></TABLE
  57366. >
  57367.     </P
  57368. ><DIV
  57369. CLASS="note"
  57370. ><BLOCKQUOTE
  57371. CLASS="note"
  57372. ><P
  57373. ><B
  57374. >Note: </B
  57375. >
  57376.       The second parameter was added in PHP 4.0.3.
  57377.      </P
  57378. ></BLOCKQUOTE
  57379. ></DIV
  57380. ><P
  57381. >      See also <A
  57382. HREF="#function.array-flip"
  57383. ><B
  57384. CLASS="function"
  57385. >array_flip()</B
  57386. ></A
  57387. >.
  57388.     </P
  57389. ></DIV
  57390. ><H1
  57391. ><A
  57392. NAME="function.array-search"
  57393. ></A
  57394. >array_search</H1
  57395. ><DIV
  57396. CLASS="refnamediv"
  57397. ><A
  57398. NAME="AEN10000"
  57399. ></A
  57400. ><P
  57401. >    (PHP 4 >= 4.0.5, PHP 5)</P
  57402. >array_search -- 
  57403.      Searches the array for a given value and returns the
  57404.      corresponding key if successful
  57405.     </DIV
  57406. ><DIV
  57407. CLASS="refsect1"
  57408. ><A
  57409. NAME="AEN10003"
  57410. ></A
  57411. ><H2
  57412. >Description</H2
  57413. >mixed <B
  57414. CLASS="methodname"
  57415. >array_search</B
  57416. > ( mixed needle, array haystack [, bool strict])<BR
  57417. ></BR
  57418. ><P
  57419. >      Searches <VAR
  57420. CLASS="parameter"
  57421. >haystack</VAR
  57422. > for
  57423.      <VAR
  57424. CLASS="parameter"
  57425. >needle</VAR
  57426. > and returns the key if it is found in
  57427.      the array, <TT
  57428. CLASS="constant"
  57429. ><B
  57430. >FALSE</B
  57431. ></TT
  57432. > otherwise.
  57433.     </P
  57434. ><DIV
  57435. CLASS="note"
  57436. ><BLOCKQUOTE
  57437. CLASS="note"
  57438. ><P
  57439. ><B
  57440. >Note: </B
  57441. >
  57442.       If <VAR
  57443. CLASS="parameter"
  57444. >needle</VAR
  57445. > is a string, the comparison is done
  57446.       in a case-sensitive manner.
  57447.      </P
  57448. ></BLOCKQUOTE
  57449. ></DIV
  57450. ><DIV
  57451. CLASS="note"
  57452. ><BLOCKQUOTE
  57453. CLASS="note"
  57454. ><P
  57455. ><B
  57456. >Note: </B
  57457. >
  57458.       Prior to PHP 4.2.0, <B
  57459. CLASS="function"
  57460. >array_search()</B
  57461. > returns
  57462.       <TT
  57463. CLASS="constant"
  57464. ><B
  57465. >NULL</B
  57466. ></TT
  57467. > on failure instead of <TT
  57468. CLASS="constant"
  57469. ><B
  57470. >FALSE</B
  57471. ></TT
  57472. >.
  57473.      </P
  57474. ></BLOCKQUOTE
  57475. ></DIV
  57476. ><P
  57477. >      If the optional third parameter <VAR
  57478. CLASS="parameter"
  57479. >strict</VAR
  57480. > is set to
  57481.      <TT
  57482. CLASS="constant"
  57483. ><B
  57484. >TRUE</B
  57485. ></TT
  57486. > then the <B
  57487. CLASS="function"
  57488. >array_search()</B
  57489. >
  57490.      will also check the types of the <VAR
  57491. CLASS="parameter"
  57492. >needle</VAR
  57493. >
  57494.      in the <VAR
  57495. CLASS="parameter"
  57496. >haystack</VAR
  57497. >.
  57498.     </P
  57499. ><P
  57500. >      If <VAR
  57501. CLASS="parameter"
  57502. >needle</VAR
  57503. > is found in
  57504.      <VAR
  57505. CLASS="parameter"
  57506. >haystack</VAR
  57507. > more than once, the first matching key
  57508.      is returned. To return the keys for all matching values, use
  57509.      <A
  57510. HREF="#function.array-keys"
  57511. ><B
  57512. CLASS="function"
  57513. >array_keys()</B
  57514. ></A
  57515. > with the optional
  57516.      <VAR
  57517. CLASS="parameter"
  57518. >search_value</VAR
  57519. > parameter instead.
  57520.     </P
  57521. ><P
  57522. >      <TABLE
  57523. WIDTH="100%"
  57524. BORDER="0"
  57525. CELLPADDING="0"
  57526. CELLSPACING="0"
  57527. CLASS="EXAMPLE"
  57528. ><TR
  57529. ><TD
  57530. ><DIV
  57531. CLASS="example"
  57532. ><A
  57533. NAME="AEN10041"
  57534. ></A
  57535. ><P
  57536. ><B
  57537. >Example 1. <B
  57538. CLASS="function"
  57539. >array_search()</B
  57540. > example</B
  57541. ></P
  57542. ><TABLE
  57543. BORDER="0"
  57544. BGCOLOR="#E0E0E0"
  57545. CELLPADDING="5"
  57546. ><TR
  57547. ><TD
  57548. ><PRE
  57549. CLASS="php"
  57550. ><?php
  57551. $array = array(0 => 'blue', 1 => 'red', 2 => 'green', 3 => 'red');
  57552.  
  57553. $key = array_search('green', $array); // $key = 2;
  57554. $key = array_search('red', $array);   // $key = 1;
  57555. ?></PRE
  57556. ></TD
  57557. ></TR
  57558. ></TABLE
  57559. ></DIV
  57560. ></TD
  57561. ></TR
  57562. ></TABLE
  57563. >
  57564.     </P
  57565. ><DIV
  57566. CLASS="warning"
  57567. ><P
  57568. ></P
  57569. ><TABLE
  57570. CLASS="warning"
  57571. BORDER="1"
  57572. WIDTH="100%"
  57573. ><TR
  57574. ><TD
  57575. ALIGN="CENTER"
  57576. ><B
  57577. >Warning</B
  57578. ></TD
  57579. ></TR
  57580. ><TR
  57581. ><TD
  57582. ALIGN="LEFT"
  57583. ><P
  57584. >This function may
  57585. return Boolean <TT
  57586. CLASS="constant"
  57587. ><B
  57588. >FALSE</B
  57589. ></TT
  57590. >, but may also return a non-Boolean value which
  57591. evaluates to <TT
  57592. CLASS="constant"
  57593. ><B
  57594. >FALSE</B
  57595. ></TT
  57596. >, such as <VAR
  57597. CLASS="literal"
  57598. >0</VAR
  57599. > or
  57600. "". Please read the section on <A
  57601. HREF="#language.types.boolean"
  57602. >Booleans</A
  57603. > for more
  57604. information. Use <A
  57605. HREF="#language.operators.comparison"
  57606. >the ===
  57607. operator</A
  57608. > for testing the return value of this
  57609. function.</P
  57610. ></TD
  57611. ></TR
  57612. ></TABLE
  57613. ></DIV
  57614. ><P
  57615. >      See also <A
  57616. HREF="#function.array-keys"
  57617. ><B
  57618. CLASS="function"
  57619. >array_keys()</B
  57620. ></A
  57621. >,
  57622.      <A
  57623. HREF="#function.array-values"
  57624. ><B
  57625. CLASS="function"
  57626. >array_values()</B
  57627. ></A
  57628. >,
  57629.      <A
  57630. HREF="#function.array-key-exists"
  57631. ><B
  57632. CLASS="function"
  57633. >array_key_exists()</B
  57634. ></A
  57635. >, and
  57636.      <A
  57637. HREF="#function.in-array"
  57638. ><B
  57639. CLASS="function"
  57640. >in_array()</B
  57641. ></A
  57642. >.
  57643.     </P
  57644. ></DIV
  57645. ><H1
  57646. ><A
  57647. NAME="function.array-shift"
  57648. ></A
  57649. >array_shift</H1
  57650. ><DIV
  57651. CLASS="refnamediv"
  57652. ><A
  57653. NAME="AEN10058"
  57654. ></A
  57655. ><P
  57656. >    (PHP 4 , PHP 5)</P
  57657. >array_shift -- 
  57658.      Shift an element off the beginning of array
  57659.     </DIV
  57660. ><DIV
  57661. CLASS="refsect1"
  57662. ><A
  57663. NAME="AEN10061"
  57664. ></A
  57665. ><H2
  57666. >Description</H2
  57667. >mixed <B
  57668. CLASS="methodname"
  57669. >array_shift</B
  57670. > ( array &array)<BR
  57671. ></BR
  57672. ><P
  57673. >      <B
  57674. CLASS="function"
  57675. >array_shift()</B
  57676. > shifts the first value of the
  57677.      <VAR
  57678. CLASS="parameter"
  57679. >array</VAR
  57680. > off and returns it, shortening the
  57681.      <VAR
  57682. CLASS="parameter"
  57683. >array</VAR
  57684. > by one element and moving everything
  57685.      down. All numerical array keys will be modified to start counting from zero
  57686.      while literal keys won't be touched. If <VAR
  57687. CLASS="parameter"
  57688. >array</VAR
  57689. > is empty 
  57690.      (or is not an array), <TT
  57691. CLASS="constant"
  57692. ><B
  57693. >NULL</B
  57694. ></TT
  57695. > will be returned.
  57696.     </P
  57697. ><DIV
  57698. CLASS="note"
  57699. ><BLOCKQUOTE
  57700. CLASS="note"
  57701. ><P
  57702. ><B
  57703. >Note: </B
  57704. >This function will 
  57705. <A
  57706. HREF="#function.reset"
  57707. ><B
  57708. CLASS="function"
  57709. >reset()</B
  57710. ></A
  57711. > the <A
  57712. HREF="#language.types.array"
  57713. ><B
  57714. CLASS="type"
  57715. >array</B
  57716. ></A
  57717. > pointer after 
  57718. use.</P
  57719. ></BLOCKQUOTE
  57720. ></DIV
  57721. ><TABLE
  57722. WIDTH="100%"
  57723. BORDER="0"
  57724. CELLPADDING="0"
  57725. CELLSPACING="0"
  57726. CLASS="EXAMPLE"
  57727. ><TR
  57728. ><TD
  57729. ><DIV
  57730. CLASS="example"
  57731. ><A
  57732. NAME="AEN10079"
  57733. ></A
  57734. ><P
  57735. ><B
  57736. >Example 1. <B
  57737. CLASS="function"
  57738. >array_shift()</B
  57739. > example</B
  57740. ></P
  57741. ><TABLE
  57742. BORDER="0"
  57743. BGCOLOR="#E0E0E0"
  57744. CELLPADDING="5"
  57745. ><TR
  57746. ><TD
  57747. ><PRE
  57748. CLASS="php"
  57749. ><?php
  57750. $stack = array("orange", "banana", "apple", "raspberry");
  57751. $fruit = array_shift($stack);
  57752. print_r($stack);
  57753. ?></PRE
  57754. ></TD
  57755. ></TR
  57756. ></TABLE
  57757. ><P
  57758. >       This would result in <VAR
  57759. CLASS="varname"
  57760. >$stack</VAR
  57761. > having 3 elements left:
  57762.      </P
  57763. ><TABLE
  57764. BORDER="0"
  57765. BGCOLOR="#E0E0E0"
  57766. CELLPADDING="5"
  57767. ><TR
  57768. ><TD
  57769. ><PRE
  57770. CLASS="php"
  57771. >Array
  57772. (
  57773.     [0] => banana
  57774.     [1] => apple
  57775.     [2] => raspberry
  57776. )</PRE
  57777. ></TD
  57778. ></TR
  57779. ></TABLE
  57780. ><P
  57781. >       and <VAR
  57782. CLASS="literal"
  57783. >orange</VAR
  57784. > will be assigned to
  57785.       <VAR
  57786. CLASS="varname"
  57787. >$fruit</VAR
  57788. >.
  57789.      </P
  57790. ></DIV
  57791. ></TD
  57792. ></TR
  57793. ></TABLE
  57794. ><P
  57795. >      See also <A
  57796. HREF="#function.array-unshift"
  57797. ><B
  57798. CLASS="function"
  57799. >array_unshift()</B
  57800. ></A
  57801. >,
  57802.      <A
  57803. HREF="#function.array-push"
  57804. ><B
  57805. CLASS="function"
  57806. >array_push()</B
  57807. ></A
  57808. >, and
  57809.      <A
  57810. HREF="#function.array-pop"
  57811. ><B
  57812. CLASS="function"
  57813. >array_pop()</B
  57814. ></A
  57815. >.
  57816.     </P
  57817. ></DIV
  57818. ><H1
  57819. ><A
  57820. NAME="function.array-slice"
  57821. ></A
  57822. >array_slice</H1
  57823. ><DIV
  57824. CLASS="refnamediv"
  57825. ><A
  57826. NAME="AEN10094"
  57827. ></A
  57828. ><P
  57829. >    (PHP 4 , PHP 5)</P
  57830. >array_slice -- Extract a slice of the array</DIV
  57831. ><DIV
  57832. CLASS="refsect1"
  57833. ><A
  57834. NAME="AEN10097"
  57835. ></A
  57836. ><H2
  57837. >Description</H2
  57838. >array <B
  57839. CLASS="methodname"
  57840. >array_slice</B
  57841. > ( array array, int offset [, int length [, bool preserve_keys]])<BR
  57842. ></BR
  57843. ><P
  57844. >      <B
  57845. CLASS="function"
  57846. >array_slice()</B
  57847. > returns the sequence of elements
  57848.      from the array <VAR
  57849. CLASS="parameter"
  57850. >array</VAR
  57851. > as specified by the
  57852.      <VAR
  57853. CLASS="parameter"
  57854. >offset</VAR
  57855. > and <VAR
  57856. CLASS="parameter"
  57857. >length</VAR
  57858. >
  57859.      parameters.
  57860.     </P
  57861. ><P
  57862. >      If <VAR
  57863. CLASS="parameter"
  57864. >offset</VAR
  57865. > is positive, the sequence will
  57866.      start at that offset in the <VAR
  57867. CLASS="parameter"
  57868. >array</VAR
  57869. >.  If
  57870.      <VAR
  57871. CLASS="parameter"
  57872. >offset</VAR
  57873. > is negative, the sequence will
  57874.      start that far from the end of the <VAR
  57875. CLASS="parameter"
  57876. >array</VAR
  57877. >.
  57878.     </P
  57879. ><P
  57880. >      If <VAR
  57881. CLASS="parameter"
  57882. >length</VAR
  57883. > is given and is positive, then
  57884.      the sequence will have that many elements in it. If
  57885.      <VAR
  57886. CLASS="parameter"
  57887. >length</VAR
  57888. > is given and is negative then the
  57889.      sequence will stop that many elements from the end of the
  57890.      array. If it is omitted, then the sequence will have everything
  57891.      from <VAR
  57892. CLASS="parameter"
  57893. >offset</VAR
  57894. > up until the end of the
  57895.      <VAR
  57896. CLASS="parameter"
  57897. >array</VAR
  57898. >.
  57899.     </P
  57900. ><P
  57901. >      Note that <B
  57902. CLASS="function"
  57903. >array_slice()</B
  57904. > will reset the array keys by
  57905.      default. Since PHP 5.0.2, you can change this behaviour by setting
  57906.      <VAR
  57907. CLASS="parameter"
  57908. >preserve_keys</VAR
  57909. > to <TT
  57910. CLASS="constant"
  57911. ><B
  57912. >TRUE</B
  57913. ></TT
  57914. >.
  57915.     </P
  57916. ><P
  57917. >      <TABLE
  57918. WIDTH="100%"
  57919. BORDER="0"
  57920. CELLPADDING="0"
  57921. CELLSPACING="0"
  57922. CLASS="EXAMPLE"
  57923. ><TR
  57924. ><TD
  57925. ><DIV
  57926. CLASS="example"
  57927. ><A
  57928. NAME="AEN10134"
  57929. ></A
  57930. ><P
  57931. ><B
  57932. >Example 1. <B
  57933. CLASS="function"
  57934. >array_slice()</B
  57935. > examples</B
  57936. ></P
  57937. ><TABLE
  57938. BORDER="0"
  57939. BGCOLOR="#E0E0E0"
  57940. CELLPADDING="5"
  57941. ><TR
  57942. ><TD
  57943. ><PRE
  57944. CLASS="php"
  57945. ><?php
  57946. $input = array("a", "b", "c", "d", "e");
  57947.  
  57948. $output = array_slice($input, 2);      // returns "c", "d", and "e"
  57949. $output = array_slice($input, -2, 1);  // returns "d"
  57950. $output = array_slice($input, 0, 3);   // returns "a", "b", and "c"
  57951.  
  57952. // note the differences in the array keys
  57953. print_r(array_slice($input, 2, -1));
  57954. print_r(array_slice($input, 2, -1, true));
  57955. ?></PRE
  57956. ></TD
  57957. ></TR
  57958. ></TABLE
  57959. ><P
  57960. >The above example will output:</P
  57961. ><TABLE
  57962. BORDER="0"
  57963. BGCOLOR="#E0E0E0"
  57964. CELLPADDING="5"
  57965. ><TR
  57966. ><TD
  57967. ><PRE
  57968. CLASS="screen"
  57969. >Array
  57970. (
  57971.     [0] => c
  57972.     [1] => d
  57973. )
  57974. Array
  57975. (
  57976.     [2] => c
  57977.     [3] => d
  57978. )</PRE
  57979. ></TD
  57980. ></TR
  57981. ></TABLE
  57982. ></DIV
  57983. ></TD
  57984. ></TR
  57985. ></TABLE
  57986. >
  57987.     </P
  57988. ><P
  57989. >      See also <A
  57990. HREF="#function.array-splice"
  57991. ><B
  57992. CLASS="function"
  57993. >array_splice()</B
  57994. ></A
  57995. > and
  57996.      <A
  57997. HREF="#function.unset"
  57998. ><B
  57999. CLASS="function"
  58000. >unset()</B
  58001. ></A
  58002. >.
  58003.     </P
  58004. ></DIV
  58005. ><H1
  58006. ><A
  58007. NAME="function.array-splice"
  58008. ></A
  58009. >array_splice</H1
  58010. ><DIV
  58011. CLASS="refnamediv"
  58012. ><A
  58013. NAME="AEN10144"
  58014. ></A
  58015. ><P
  58016. >    (PHP 4 , PHP 5)</P
  58017. >array_splice -- 
  58018.      Remove a portion of the array and replace it with something
  58019.      else
  58020.     </DIV
  58021. ><DIV
  58022. CLASS="refsect1"
  58023. ><A
  58024. NAME="AEN10147"
  58025. ></A
  58026. ><H2
  58027. >Description</H2
  58028. >array <B
  58029. CLASS="methodname"
  58030. >array_splice</B
  58031. > ( array &input, int offset [, int length [, array replacement]])<BR
  58032. ></BR
  58033. ><P
  58034. >      <B
  58035. CLASS="function"
  58036. >array_splice()</B
  58037. > removes the elements designated
  58038.      by <VAR
  58039. CLASS="parameter"
  58040. >offset</VAR
  58041. > and
  58042.      <VAR
  58043. CLASS="parameter"
  58044. >length</VAR
  58045. > from the
  58046.      <VAR
  58047. CLASS="parameter"
  58048. >input</VAR
  58049. > array, and replaces them with the
  58050.      elements of the <VAR
  58051. CLASS="parameter"
  58052. >replacement</VAR
  58053. > array, if
  58054.      supplied. It returns an array containing the extracted elements.
  58055.     </P
  58056. ><P
  58057. >      If <VAR
  58058. CLASS="parameter"
  58059. >offset</VAR
  58060. > is positive then the start of
  58061.      removed portion is at that offset from the beginning of the
  58062.      <VAR
  58063. CLASS="parameter"
  58064. >input</VAR
  58065. > array.  If
  58066.      <VAR
  58067. CLASS="parameter"
  58068. >offset</VAR
  58069. > is negative then it starts that far
  58070.      from the end of the <VAR
  58071. CLASS="parameter"
  58072. >input</VAR
  58073. > array.
  58074.     </P
  58075. ><P
  58076. >      If <VAR
  58077. CLASS="parameter"
  58078. >length</VAR
  58079. > is omitted, removes everything
  58080.      from <VAR
  58081. CLASS="parameter"
  58082. >offset</VAR
  58083. > to the end of the array.  If
  58084.      <VAR
  58085. CLASS="parameter"
  58086. >length</VAR
  58087. > is specified and is positive, then
  58088.      that many elements will be removed. If
  58089.      <VAR
  58090. CLASS="parameter"
  58091. >length</VAR
  58092. > is specified and is negative then
  58093.      the end of the removed portion will be that many elements from
  58094.      the end of the array.  Tip: to remove everything from
  58095.      <VAR
  58096. CLASS="parameter"
  58097. >offset</VAR
  58098. > to the end of the array when
  58099.      <VAR
  58100. CLASS="parameter"
  58101. >replacement</VAR
  58102. > is also specified, use
  58103.      <VAR
  58104. CLASS="literal"
  58105. >count($input)</VAR
  58106. > for
  58107.      <VAR
  58108. CLASS="parameter"
  58109. >length</VAR
  58110. >.
  58111.     </P
  58112. ><P
  58113. >      If <VAR
  58114. CLASS="parameter"
  58115. >replacement</VAR
  58116. > array is specified, then
  58117.      the removed elements are replaced with elements from this array.
  58118.      If <VAR
  58119. CLASS="parameter"
  58120. >offset</VAR
  58121. > and
  58122.      <VAR
  58123. CLASS="parameter"
  58124. >length</VAR
  58125. > are such that nothing is removed,
  58126.      then the elements from the <VAR
  58127. CLASS="parameter"
  58128. >replacement</VAR
  58129. >
  58130.      array are inserted in the place specified by the
  58131.      <VAR
  58132. CLASS="parameter"
  58133. >offset</VAR
  58134. >. Tip: if the replacement is just
  58135.      one element it is not necessary to put <VAR
  58136. CLASS="literal"
  58137. >array()</VAR
  58138. >
  58139.      around it, unless the element is an array itself.
  58140.     </P
  58141. ><P
  58142. >      The following statements change the values of <VAR
  58143. CLASS="varname"
  58144. >$input</VAR
  58145. >
  58146.      the same way:
  58147.    <DIV
  58148. CLASS="table"
  58149. ><A
  58150. NAME="AEN10193"
  58151. ></A
  58152. ><P
  58153. ><B
  58154. >Table 1. <B
  58155. CLASS="function"
  58156. >array_splice()</B
  58157. > equivalents</B
  58158. ></P
  58159. ><TABLE
  58160. BORDER="1"
  58161. CLASS="CALSTABLE"
  58162. ><COL><COL><TBODY
  58163. ><TR
  58164. ><TD
  58165. >         array_push($input, $x, $y) 
  58166.        </TD
  58167. ><TD
  58168. >         array_splice($input, count($input), 0, array($x, $y))
  58169.        </TD
  58170. ></TR
  58171. ><TR
  58172. ><TD
  58173. >         array_pop($input) 
  58174.        </TD
  58175. ><TD
  58176. >         array_splice($input, -1)
  58177.        </TD
  58178. ></TR
  58179. ><TR
  58180. ><TD
  58181. >         array_shift($input)
  58182.        </TD
  58183. ><TD
  58184. >         array_splice($input, 0, 1)
  58185.        </TD
  58186. ></TR
  58187. ><TR
  58188. ><TD
  58189. >         array_unshift($input, $x, $y)
  58190.        </TD
  58191. ><TD
  58192. >         array_splice($input, 0, 0, array($x, $y))
  58193.        </TD
  58194. ></TR
  58195. ><TR
  58196. ><TD
  58197. >         $input[$x] = $y // for arrays where key equals offset
  58198.        </TD
  58199. ><TD
  58200. >         array_splice($input, $x, 1, $y)
  58201.        </TD
  58202. ></TR
  58203. ></TBODY
  58204. ></TABLE
  58205. ></DIV
  58206. >
  58207.     </P
  58208. ><P
  58209. >      Returns the array consisting of removed elements.
  58210.     </P
  58211. ><P
  58212. >      <TABLE
  58213. WIDTH="100%"
  58214. BORDER="0"
  58215. CELLPADDING="0"
  58216. CELLSPACING="0"
  58217. CLASS="EXAMPLE"
  58218. ><TR
  58219. ><TD
  58220. ><DIV
  58221. CLASS="example"
  58222. ><A
  58223. NAME="AEN10215"
  58224. ></A
  58225. ><P
  58226. ><B
  58227. >Example 1. <B
  58228. CLASS="function"
  58229. >array_splice()</B
  58230. > examples</B
  58231. ></P
  58232. ><TABLE
  58233. BORDER="0"
  58234. BGCOLOR="#E0E0E0"
  58235. CELLPADDING="5"
  58236. ><TR
  58237. ><TD
  58238. ><PRE
  58239. CLASS="php"
  58240. ><?php
  58241. $input = array("red", "green", "blue", "yellow");
  58242. array_splice($input, 2);
  58243. // $input is now array("red", "green")
  58244.  
  58245. $input = array("red", "green", "blue", "yellow");
  58246. array_splice($input, 1, -1);
  58247. // $input is now array("red", "yellow")
  58248.  
  58249. $input = array("red", "green", "blue", "yellow");
  58250. array_splice($input, 1, count($input), "orange");
  58251. // $input is now array("red", "orange")
  58252.  
  58253. $input = array("red", "green", "blue", "yellow");
  58254. array_splice($input, -1, 1, array("black", "maroon"));
  58255. // $input is now array("red", "green",
  58256. //          "blue", "black", "maroon")
  58257.  
  58258. $input = array("red", "green", "blue", "yellow");
  58259. array_splice($input, 3, 0, "purple");
  58260. // $input is now array("red", "green",
  58261. //          "blue", "purple", "yellow");
  58262. ?></PRE
  58263. ></TD
  58264. ></TR
  58265. ></TABLE
  58266. ></DIV
  58267. ></TD
  58268. ></TR
  58269. ></TABLE
  58270. >
  58271.     </P
  58272. ><P
  58273. >      See also <A
  58274. HREF="#function.array-slice"
  58275. ><B
  58276. CLASS="function"
  58277. >array_slice()</B
  58278. ></A
  58279. >, 
  58280.      <A
  58281. HREF="#function.unset"
  58282. ><B
  58283. CLASS="function"
  58284. >unset()</B
  58285. ></A
  58286. >, and
  58287.      <A
  58288. HREF="#function.array-merge"
  58289. ><B
  58290. CLASS="function"
  58291. >array_merge()</B
  58292. ></A
  58293. >.
  58294.     </P
  58295. ></DIV
  58296. ><H1
  58297. ><A
  58298. NAME="function.array-sum"
  58299. ></A
  58300. >array_sum</H1
  58301. ><DIV
  58302. CLASS="refnamediv"
  58303. ><A
  58304. NAME="AEN10224"
  58305. ></A
  58306. ><P
  58307. >    (PHP 4 >= 4.0.4, PHP 5)</P
  58308. >array_sum -- 
  58309.      Calculate the sum of values in an array
  58310.     </DIV
  58311. ><DIV
  58312. CLASS="refsect1"
  58313. ><A
  58314. NAME="AEN10227"
  58315. ></A
  58316. ><H2
  58317. >Description</H2
  58318. >number <B
  58319. CLASS="methodname"
  58320. >array_sum</B
  58321. > ( array array)<BR
  58322. ></BR
  58323. ><P
  58324. >      <B
  58325. CLASS="function"
  58326. >array_sum()</B
  58327. > returns the sum of values
  58328.      in an array as an integer or float.
  58329.     </P
  58330. ><P
  58331. >      <TABLE
  58332. WIDTH="100%"
  58333. BORDER="0"
  58334. CELLPADDING="0"
  58335. CELLSPACING="0"
  58336. CLASS="EXAMPLE"
  58337. ><TR
  58338. ><TD
  58339. ><DIV
  58340. CLASS="example"
  58341. ><A
  58342. NAME="AEN10238"
  58343. ></A
  58344. ><P
  58345. ><B
  58346. >Example 1. <B
  58347. CLASS="function"
  58348. >array_sum()</B
  58349. > examples</B
  58350. ></P
  58351. ><TABLE
  58352. BORDER="0"
  58353. BGCOLOR="#E0E0E0"
  58354. CELLPADDING="5"
  58355. ><TR
  58356. ><TD
  58357. ><PRE
  58358. CLASS="php"
  58359. ><?php
  58360. $a = array(2, 4, 6, 8);
  58361. echo "sum(a) = " . array_sum($a) . "\n";
  58362.  
  58363. $b = array("a" => 1.2, "b" => 2.3, "c" => 3.4);
  58364. echo "sum(b) = " . array_sum($b) . "\n";
  58365. ?></PRE
  58366. ></TD
  58367. ></TR
  58368. ></TABLE
  58369. ><P
  58370. >The above example will output:</P
  58371. ><TABLE
  58372. BORDER="0"
  58373. BGCOLOR="#E0E0E0"
  58374. CELLPADDING="5"
  58375. ><TR
  58376. ><TD
  58377. ><PRE
  58378. CLASS="screen"
  58379. >sum(a) = 20
  58380. sum(b) = 6.9</PRE
  58381. ></TD
  58382. ></TR
  58383. ></TABLE
  58384. ></DIV
  58385. ></TD
  58386. ></TR
  58387. ></TABLE
  58388. >
  58389.     </P
  58390. ><DIV
  58391. CLASS="note"
  58392. ><BLOCKQUOTE
  58393. CLASS="note"
  58394. ><P
  58395. ><B
  58396. >Note: </B
  58397. >
  58398.       PHP versions prior to 4.2.1 modified the passed array
  58399.       itself and converted strings to numbers (which most
  58400.       of the time converted them to zero, depending on
  58401.       their value).
  58402.      </P
  58403. ></BLOCKQUOTE
  58404. ></DIV
  58405. ></DIV
  58406. ><H1
  58407. ><A
  58408. NAME="function.array-udiff-assoc"
  58409. ></A
  58410. >array_udiff_assoc</H1
  58411. ><DIV
  58412. CLASS="refnamediv"
  58413. ><A
  58414. NAME="AEN10247"
  58415. ></A
  58416. ><P
  58417. >    (PHP 5)</P
  58418. >array_udiff_assoc -- Computes the difference of arrays with additional index check, compares data by a callback function</DIV
  58419. ><DIV
  58420. CLASS="refsect1"
  58421. ><A
  58422. NAME="AEN10250"
  58423. ></A
  58424. ><H2
  58425. >Description</H2
  58426. >array <B
  58427. CLASS="methodname"
  58428. >array_udiff_assoc</B
  58429. > ( array array1, array array2 [, array ..., callback data_compare_func])<BR
  58430. ></BR
  58431. ><P
  58432. >      <B
  58433. CLASS="function"
  58434. >array_udiff_assoc()</B
  58435. > returns an <A
  58436. HREF="#language.types.array"
  58437. ><B
  58438. CLASS="type"
  58439. >array</B
  58440. ></A
  58441. >
  58442.      containing all the values from <VAR
  58443. CLASS="parameter"
  58444. >array1</VAR
  58445. >
  58446.      that are not present in any of the other arguments.
  58447.      Note that the keys are used in the comparison unlike 
  58448.      <A
  58449. HREF="#function.array-diff"
  58450. ><B
  58451. CLASS="function"
  58452. >array_diff()</B
  58453. ></A
  58454. > and <A
  58455. HREF="#function.array-udiff"
  58456. ><B
  58457. CLASS="function"
  58458. >array_udiff()</B
  58459. ></A
  58460. >.
  58461.      The comparison of arrays' data is performed by using an user-supplied
  58462.      callback. In this aspect the behaviour is opposite to the behaviour of
  58463.      <A
  58464. HREF="#function.array-diff-assoc"
  58465. ><B
  58466. CLASS="function"
  58467. >array_diff_assoc()</B
  58468. ></A
  58469. > which uses internal function for
  58470.      comparison.
  58471.     </P
  58472. ><P
  58473. >      <TABLE
  58474. WIDTH="100%"
  58475. BORDER="0"
  58476. CELLPADDING="0"
  58477. CELLSPACING="0"
  58478. CLASS="EXAMPLE"
  58479. ><TR
  58480. ><TD
  58481. ><DIV
  58482. CLASS="example"
  58483. ><A
  58484. NAME="AEN10275"
  58485. ></A
  58486. ><P
  58487. ><B
  58488. >Example 1. <B
  58489. CLASS="function"
  58490. >array_udiff_assoc()</B
  58491. > example</B
  58492. ></P
  58493. ><TABLE
  58494. BORDER="0"
  58495. BGCOLOR="#E0E0E0"
  58496. CELLPADDING="5"
  58497. ><TR
  58498. ><TD
  58499. ><PRE
  58500. CLASS="php"
  58501. ><?php
  58502. class cr {
  58503.     private $priv_member;
  58504.     function cr($val) 
  58505.     {
  58506.         $this->priv_member = $val;
  58507.     }
  58508.     
  58509.     function comp_func_cr($a, $b) 
  58510.     {
  58511.         if ($a->priv_member === $b->priv_member) return 0;
  58512.         return ($a->priv_member > $b->priv_member)? 1:-1;
  58513.     }
  58514. }
  58515.  
  58516. $a = array("0.1" => new cr(9), "0.5" => new cr(12), 0 => new cr(23), 1=> new cr(4), 2 => new cr(-15),);
  58517. $b = array("0.2" => new cr(9), "0.5" => new cr(22), 0 => new cr(3), 1=> new cr(4), 2 => new cr(-15),);
  58518.  
  58519. $result = array_udiff_assoc($a, $b, array("cr", "comp_func_cr"));
  58520. print_r($result);
  58521. ?></PRE
  58522. ></TD
  58523. ></TR
  58524. ></TABLE
  58525. ><P
  58526. >The above example will output:</P
  58527. ><TABLE
  58528. BORDER="0"
  58529. BGCOLOR="#E0E0E0"
  58530. CELLPADDING="5"
  58531. ><TR
  58532. ><TD
  58533. ><PRE
  58534. CLASS="screen"
  58535. >Array
  58536. (
  58537.     [0.1] => cr Object
  58538.         (
  58539.             [priv_member:private] => 9
  58540.         )
  58541.  
  58542.     [0.5] => cr Object
  58543.         (
  58544.             [priv_member:private] => 12
  58545.         )
  58546.  
  58547.     [0] => cr Object
  58548.         (
  58549.             [priv_member:private] => 23
  58550.         )
  58551. )</PRE
  58552. ></TD
  58553. ></TR
  58554. ></TABLE
  58555. ></DIV
  58556. ></TD
  58557. ></TR
  58558. ></TABLE
  58559. >
  58560.     </P
  58561. ><P
  58562. >      In our example above you see the <VAR
  58563. CLASS="literal"
  58564. >"1" => new cr(4)</VAR
  58565. >
  58566.      pair is present in both arrays and thus it is not in the ouput from the
  58567.      function.
  58568.     </P
  58569. ><P
  58570. >      For comparison is used the user supplied callback function.
  58571.      It must return an integer less than, equal
  58572.      to, or greater than zero if the first argument is considered to
  58573.      be respectively less than, equal to, or greater than the
  58574.      second.
  58575.     </P
  58576. ><DIV
  58577. CLASS="note"
  58578. ><BLOCKQUOTE
  58579. CLASS="note"
  58580. ><P
  58581. ><B
  58582. >Note: </B
  58583. >
  58584.       Please note that this function only checks one dimension of a n-dimensional
  58585.       array. Of course you can check deeper dimensions by using, for example, 
  58586.       <VAR
  58587. CLASS="literal"
  58588. >array_udiff_assoc($array1[0], $array2[0], "some_comparison_func");</VAR
  58589. >.
  58590.      </P
  58591. ></BLOCKQUOTE
  58592. ></DIV
  58593. ><P
  58594. >      See also
  58595.      <A
  58596. HREF="#function.array-diff"
  58597. ><B
  58598. CLASS="function"
  58599. >array_diff()</B
  58600. ></A
  58601. >,
  58602.      <A
  58603. HREF="#function.array-diff-assoc"
  58604. ><B
  58605. CLASS="function"
  58606. >array_diff_assoc()</B
  58607. ></A
  58608. >,
  58609.      <A
  58610. HREF="#function.array-diff-uassoc"
  58611. ><B
  58612. CLASS="function"
  58613. >array_diff_uassoc()</B
  58614. ></A
  58615. >,
  58616.      <A
  58617. HREF="#function.array-udiff"
  58618. ><B
  58619. CLASS="function"
  58620. >array_udiff()</B
  58621. ></A
  58622. >,
  58623.      <A
  58624. HREF="#function.array-udiff-uassoc"
  58625. ><B
  58626. CLASS="function"
  58627. >array_udiff_uassoc()</B
  58628. ></A
  58629. >, 
  58630.      <A
  58631. HREF="#function.array-intersect"
  58632. ><B
  58633. CLASS="function"
  58634. >array_intersect()</B
  58635. ></A
  58636. >,  
  58637.      <A
  58638. HREF="#function.array-intersect-assoc"
  58639. ><B
  58640. CLASS="function"
  58641. >array_intersect_assoc()</B
  58642. ></A
  58643. >,
  58644.      <A
  58645. HREF="#function.array-uintersect"
  58646. ><B
  58647. CLASS="function"
  58648. >array_uintersect()</B
  58649. ></A
  58650. >,  
  58651.      <A
  58652. HREF="#function.array-uintersect-assoc"
  58653. ><B
  58654. CLASS="function"
  58655. >array_uintersect_assoc()</B
  58656. ></A
  58657. > and 
  58658.      <A
  58659. HREF="#function.array-uintersect-uassoc"
  58660. ><B
  58661. CLASS="function"
  58662. >array_uintersect_uassoc()</B
  58663. ></A
  58664. >.
  58665.     </P
  58666. ></DIV
  58667. ><H1
  58668. ><A
  58669. NAME="function.array-udiff-uassoc"
  58670. ></A
  58671. >array_udiff_uassoc</H1
  58672. ><DIV
  58673. CLASS="refnamediv"
  58674. ><A
  58675. NAME="AEN10299"
  58676. ></A
  58677. ><P
  58678. >    (PHP 5)</P
  58679. >array_udiff_uassoc -- Computes the difference of arrays with additional index check, compares data and indexes by a callback function</DIV
  58680. ><DIV
  58681. CLASS="refsect1"
  58682. ><A
  58683. NAME="AEN10302"
  58684. ></A
  58685. ><H2
  58686. >Description</H2
  58687. >array <B
  58688. CLASS="methodname"
  58689. >array_udiff_uassoc</B
  58690. > ( array array1, array array2 [, array ..., callback data_compare_func, callback key_compare_func])<BR
  58691. ></BR
  58692. ><P
  58693. >      <B
  58694. CLASS="function"
  58695. >array_udiff_uassoc()</B
  58696. > returns an <A
  58697. HREF="#language.types.array"
  58698. ><B
  58699. CLASS="type"
  58700. >array</B
  58701. ></A
  58702. >
  58703.      containing all the values from <VAR
  58704. CLASS="parameter"
  58705. >array1</VAR
  58706. >
  58707.      that are not present in any of the other arguments.
  58708.      Note that the keys are used in the comparison unlike 
  58709.      <A
  58710. HREF="#function.array-diff"
  58711. ><B
  58712. CLASS="function"
  58713. >array_diff()</B
  58714. ></A
  58715. > and <A
  58716. HREF="#function.array-udiff"
  58717. ><B
  58718. CLASS="function"
  58719. >array_udiff()</B
  58720. ></A
  58721. >.
  58722.      The comparison of arrays' data is performed by using an user-supplied
  58723.      callback : <VAR
  58724. CLASS="parameter"
  58725. >data_compare_func</VAR
  58726. >. In this aspect
  58727.      the behaviour is opposite to the behaviour of
  58728.      <A
  58729. HREF="#function.array-diff-assoc"
  58730. ><B
  58731. CLASS="function"
  58732. >array_diff_assoc()</B
  58733. ></A
  58734. > which uses internal function for
  58735.      comparison. The comparison of keys (indices) is done also by the 
  58736.      callback function <VAR
  58737. CLASS="parameter"
  58738. >key_compare_func</VAR
  58739. >. This
  58740.      behaviour is unlike what <A
  58741. HREF="#function.array-udiff-assoc"
  58742. ><B
  58743. CLASS="function"
  58744. >array_udiff_assoc()</B
  58745. ></A
  58746. > does, since
  58747.      the latter compares the indices by using an internal function.
  58748.     </P
  58749. ><P
  58750. >      <TABLE
  58751. WIDTH="100%"
  58752. BORDER="0"
  58753. CELLPADDING="0"
  58754. CELLSPACING="0"
  58755. CLASS="EXAMPLE"
  58756. ><TR
  58757. ><TD
  58758. ><DIV
  58759. CLASS="example"
  58760. ><A
  58761. NAME="AEN10333"
  58762. ></A
  58763. ><P
  58764. ><B
  58765. >Example 1. <B
  58766. CLASS="function"
  58767. >array_udiff_uassoc()</B
  58768. > example</B
  58769. ></P
  58770. ><TABLE
  58771. BORDER="0"
  58772. BGCOLOR="#E0E0E0"
  58773. CELLPADDING="5"
  58774. ><TR
  58775. ><TD
  58776. ><PRE
  58777. CLASS="php"
  58778. ><?php
  58779. class cr {
  58780.     private $priv_member;
  58781.     function cr($val) 
  58782.     {
  58783.         $this->priv_member = $val;
  58784.     }
  58785.  
  58786.     function comp_func_cr($a, $b) 
  58787.     {
  58788.         if ($a->priv_member === $b->priv_member) return 0;
  58789.         return ($a->priv_member > $b->priv_member)? 1:-1;
  58790.     }
  58791.     
  58792.     function comp_func_key($a, $b) 
  58793.     {
  58794.         if ($a === $b) return 0;
  58795.         return ($a > $b)? 1:-1;
  58796.     }
  58797. }
  58798. $a = array("0.1" => new cr(9), "0.5" => new cr(12), 0 => new cr(23), 1=> new cr(4), 2 => new cr(-15),);
  58799. $b = array("0.2" => new cr(9), "0.5" => new cr(22), 0 => new cr(3), 1=> new cr(4), 2 => new cr(-15),);
  58800.  
  58801. $result = array_udiff_uassoc($a, $b, array("cr", "comp_func_cr"), array("cr", "comp_func_key"));
  58802. print_r($result);
  58803. ?></PRE
  58804. ></TD
  58805. ></TR
  58806. ></TABLE
  58807. ><P
  58808. >The above example will output:</P
  58809. ><TABLE
  58810. BORDER="0"
  58811. BGCOLOR="#E0E0E0"
  58812. CELLPADDING="5"
  58813. ><TR
  58814. ><TD
  58815. ><PRE
  58816. CLASS="screen"
  58817. >Array
  58818. (
  58819.     [0.1] => cr Object
  58820.         (
  58821.             [priv_member:private] => 9
  58822.         )
  58823.  
  58824.     [0.5] => cr Object
  58825.         (
  58826.             [priv_member:private] => 12
  58827.         )
  58828.  
  58829.     [0] => cr Object
  58830.         (
  58831.             [priv_member:private] => 23
  58832.         )
  58833. )</PRE
  58834. ></TD
  58835. ></TR
  58836. ></TABLE
  58837. ></DIV
  58838. ></TD
  58839. ></TR
  58840. ></TABLE
  58841. >
  58842.     </P
  58843. ><P
  58844. >      In our example above you see the <VAR
  58845. CLASS="literal"
  58846. >"1" => new cr(4)</VAR
  58847. >
  58848.      pair is present in both arrays and thus it is not in the ouput from the
  58849.      function. Keep in mind that you have to supply 2 callback functions.
  58850.     </P
  58851. ><P
  58852. >      For comparison is used the user supplied callback function.
  58853.      It must return an integer less than, equal
  58854.      to, or greater than zero if the first argument is considered to
  58855.      be respectively less than, equal to, or greater than the
  58856.      second.
  58857.     </P
  58858. ><DIV
  58859. CLASS="note"
  58860. ><BLOCKQUOTE
  58861. CLASS="note"
  58862. ><P
  58863. ><B
  58864. >Note: </B
  58865. >
  58866.       Please note that this function only checks one dimension of a n-dimensional
  58867.       array. Of course you can check deeper dimensions by using, for example, 
  58868.       <VAR
  58869. CLASS="literal"
  58870. >array_udiff_uassoc($array1[0], $array2[0], "data_compare_func",
  58871.       "key_compare_func");</VAR
  58872. >.
  58873.      </P
  58874. ></BLOCKQUOTE
  58875. ></DIV
  58876. ><P
  58877. >      See also
  58878.      <A
  58879. HREF="#function.array-diff"
  58880. ><B
  58881. CLASS="function"
  58882. >array_diff()</B
  58883. ></A
  58884. >,
  58885.      <A
  58886. HREF="#function.array-diff-assoc"
  58887. ><B
  58888. CLASS="function"
  58889. >array_diff_assoc()</B
  58890. ></A
  58891. >,
  58892.      <A
  58893. HREF="#function.array-diff-uassoc"
  58894. ><B
  58895. CLASS="function"
  58896. >array_diff_uassoc()</B
  58897. ></A
  58898. >,
  58899.      <A
  58900. HREF="#function.array-udiff"
  58901. ><B
  58902. CLASS="function"
  58903. >array_udiff()</B
  58904. ></A
  58905. >,
  58906.      <A
  58907. HREF="#function.array-udiff-assoc"
  58908. ><B
  58909. CLASS="function"
  58910. >array_udiff_assoc()</B
  58911. ></A
  58912. >, 
  58913.      <A
  58914. HREF="#function.array-intersect"
  58915. ><B
  58916. CLASS="function"
  58917. >array_intersect()</B
  58918. ></A
  58919. >,  
  58920.      <A
  58921. HREF="#function.array-intersect-assoc"
  58922. ><B
  58923. CLASS="function"
  58924. >array_intersect_assoc()</B
  58925. ></A
  58926. >,
  58927.      <A
  58928. HREF="#function.array-uintersect"
  58929. ><B
  58930. CLASS="function"
  58931. >array_uintersect()</B
  58932. ></A
  58933. >,  
  58934.      <A
  58935. HREF="#function.array-uintersect-assoc"
  58936. ><B
  58937. CLASS="function"
  58938. >array_uintersect_assoc()</B
  58939. ></A
  58940. > and 
  58941.      <A
  58942. HREF="#function.array-uintersect-uassoc"
  58943. ><B
  58944. CLASS="function"
  58945. >array_uintersect_uassoc()</B
  58946. ></A
  58947. >.
  58948.     </P
  58949. ></DIV
  58950. ><H1
  58951. ><A
  58952. NAME="function.array-udiff"
  58953. ></A
  58954. >array_udiff</H1
  58955. ><DIV
  58956. CLASS="refnamediv"
  58957. ><A
  58958. NAME="AEN10357"
  58959. ></A
  58960. ><P
  58961. >    (PHP 5)</P
  58962. >array_udiff -- Computes the difference of arrays by using a callback function for data comparison</DIV
  58963. ><DIV
  58964. CLASS="refsect1"
  58965. ><A
  58966. NAME="AEN10360"
  58967. ></A
  58968. ><H2
  58969. >Description</H2
  58970. >array <B
  58971. CLASS="methodname"
  58972. >array_udiff</B
  58973. > ( array array1, array array2 [, array ..., callback data_compare_func])<BR
  58974. ></BR
  58975. ><P
  58976. >      <B
  58977. CLASS="function"
  58978. >array_udiff()</B
  58979. > returns an array
  58980.      containing all the values of <VAR
  58981. CLASS="parameter"
  58982. >array1</VAR
  58983. >
  58984.      that are not present in any of the other arguments.
  58985.      Note that keys are preserved. For the comparison of the data
  58986.      <VAR
  58987. CLASS="parameter"
  58988. >data_compare_func</VAR
  58989. > is used.
  58990.      It must return an integer less than, equal
  58991.      to, or greater than zero if the first argument is considered to
  58992.      be respectively less than, equal to, or greater than the
  58993.      second. This is unlike <A
  58994. HREF="#function.array-diff"
  58995. ><B
  58996. CLASS="function"
  58997. >array_diff()</B
  58998. ></A
  58999. > which uses an
  59000.      internal function for comparing the data.
  59001.     </P
  59002. ><P
  59003. >      <TABLE
  59004. WIDTH="100%"
  59005. BORDER="0"
  59006. CELLPADDING="0"
  59007. CELLSPACING="0"
  59008. CLASS="EXAMPLE"
  59009. ><TR
  59010. ><TD
  59011. ><DIV
  59012. CLASS="example"
  59013. ><A
  59014. NAME="AEN10383"
  59015. ></A
  59016. ><P
  59017. ><B
  59018. >Example 1. <B
  59019. CLASS="function"
  59020. >array_udiff()</B
  59021. > example</B
  59022. ></P
  59023. ><TABLE
  59024. BORDER="0"
  59025. BGCOLOR="#E0E0E0"
  59026. CELLPADDING="5"
  59027. ><TR
  59028. ><TD
  59029. ><PRE
  59030. CLASS="php"
  59031. ><?php
  59032. class cr {
  59033.     private $priv_member;
  59034.     function cr($val) 
  59035.     {
  59036.         $this->priv_member = $val;
  59037.     }
  59038.     
  59039.     function comp_func_cr($a, $b) 
  59040.     {
  59041.         if ($a->priv_member === $b->priv_member) return 0;
  59042.         return ($a->priv_member > $b->priv_member)? 1:-1;
  59043.     }
  59044. }
  59045. $a = array("0.1" => new cr(9), "0.5" => new cr(12), 0 => new cr(23), 1=> new cr(4), 2 => new cr(-15),);
  59046. $b = array("0.2" => new cr(9), "0.5" => new cr(22), 0 => new cr(3), 1=> new cr(4), 2 => new cr(-15),);
  59047.  
  59048. $result = array_udiff($a, $b, array("cr", "comp_func_cr"));
  59049. print_r($result);
  59050. ?></PRE
  59051. ></TD
  59052. ></TR
  59053. ></TABLE
  59054. ><P
  59055. >The above example will output:</P
  59056. ><TABLE
  59057. BORDER="0"
  59058. BGCOLOR="#E0E0E0"
  59059. CELLPADDING="5"
  59060. ><TR
  59061. ><TD
  59062. ><PRE
  59063. CLASS="screen"
  59064. >Array
  59065. (
  59066.     [0.5] => cr Object
  59067.         (
  59068.             [priv_member:private] => 12
  59069.         )
  59070.  
  59071.     [0] => cr Object
  59072.         (
  59073.             [priv_member:private] => 23
  59074.         )
  59075.  
  59076. )</PRE
  59077. ></TD
  59078. ></TR
  59079. ></TABLE
  59080. ></DIV
  59081. ></TD
  59082. ></TR
  59083. ></TABLE
  59084. >
  59085.     </P
  59086. ><DIV
  59087. CLASS="note"
  59088. ><BLOCKQUOTE
  59089. CLASS="note"
  59090. ><P
  59091. ><B
  59092. >Note: </B
  59093. >
  59094.       Two elements are considered equal if and only if
  59095.       <VAR
  59096. CLASS="literal"
  59097. >(string) $elem1 === (string) $elem2</VAR
  59098. >. In words:
  59099.       when the string representation is the same.
  59100.      </P
  59101. ></BLOCKQUOTE
  59102. ></DIV
  59103. ><DIV
  59104. CLASS="note"
  59105. ><BLOCKQUOTE
  59106. CLASS="note"
  59107. ><P
  59108. ><B
  59109. >Note: </B
  59110. >
  59111.       Please note that this function only checks one dimension of a n-dimensional
  59112.       array. Of course you can check deeper dimensions by using
  59113.       <VAR
  59114. CLASS="literal"
  59115. >array_udiff($array1[0], $array2[0], "data_compare_func");</VAR
  59116. >.
  59117.      </P
  59118. ></BLOCKQUOTE
  59119. ></DIV
  59120. ><P
  59121. >      See also
  59122.      <A
  59123. HREF="#function.array-diff"
  59124. ><B
  59125. CLASS="function"
  59126. >array_diff()</B
  59127. ></A
  59128. >,
  59129.      <A
  59130. HREF="#function.array-diff-assoc"
  59131. ><B
  59132. CLASS="function"
  59133. >array_diff_assoc()</B
  59134. ></A
  59135. >,
  59136.      <A
  59137. HREF="#function.array-diff-uassoc"
  59138. ><B
  59139. CLASS="function"
  59140. >array_diff_uassoc()</B
  59141. ></A
  59142. >,
  59143.      <A
  59144. HREF="#function.array-udiff-assoc"
  59145. ><B
  59146. CLASS="function"
  59147. >array_udiff_assoc()</B
  59148. ></A
  59149. >, 
  59150.      <A
  59151. HREF="#function.array-udiff-uassoc"
  59152. ><B
  59153. CLASS="function"
  59154. >array_udiff_uassoc()</B
  59155. ></A
  59156. >, 
  59157.      <A
  59158. HREF="#function.array-intersect"
  59159. ><B
  59160. CLASS="function"
  59161. >array_intersect()</B
  59162. ></A
  59163. >,  
  59164.      <A
  59165. HREF="#function.array-intersect-assoc"
  59166. ><B
  59167. CLASS="function"
  59168. >array_intersect_assoc()</B
  59169. ></A
  59170. >,
  59171.      <A
  59172. HREF="#function.array-uintersect"
  59173. ><B
  59174. CLASS="function"
  59175. >array_uintersect()</B
  59176. ></A
  59177. >,  
  59178.      <A
  59179. HREF="#function.array-uintersect-assoc"
  59180. ><B
  59181. CLASS="function"
  59182. >array_uintersect_assoc()</B
  59183. ></A
  59184. > and 
  59185.      <A
  59186. HREF="#function.array-uintersect-uassoc"
  59187. ><B
  59188. CLASS="function"
  59189. >array_uintersect_uassoc()</B
  59190. ></A
  59191. >.
  59192.     </P
  59193. ></DIV
  59194. ><H1
  59195. ><A
  59196. NAME="function.array-uintersect-assoc"
  59197. ></A
  59198. >array_uintersect_assoc</H1
  59199. ><DIV
  59200. CLASS="refnamediv"
  59201. ><A
  59202. NAME="AEN10407"
  59203. ></A
  59204. ><P
  59205. >    (PHP 5)</P
  59206. >array_uintersect_assoc -- Computes the intersection of arrays with additional index check, compares data by a callback function</DIV
  59207. ><DIV
  59208. CLASS="refsect1"
  59209. ><A
  59210. NAME="AEN10410"
  59211. ></A
  59212. ><H2
  59213. >Description</H2
  59214. >array <B
  59215. CLASS="methodname"
  59216. >array_uintersect_assoc</B
  59217. > ( array array1, array array2 [, array ..., callback data_compare_func])<BR
  59218. ></BR
  59219. ><P
  59220. >      <B
  59221. CLASS="function"
  59222. >array_uintersect_assoc()</B
  59223. > returns an array
  59224.      containing all the values of <VAR
  59225. CLASS="parameter"
  59226. >array1</VAR
  59227. >
  59228.      that are present in all the arguments. Note that the keys are used in
  59229.      the comparison unlike in <A
  59230. HREF="#function.array-uintersect"
  59231. ><B
  59232. CLASS="function"
  59233. >array_uintersect()</B
  59234. ></A
  59235. >.
  59236.      The data is compared by using a callback function.
  59237.     </P
  59238. ><P
  59239. >      <TABLE
  59240. WIDTH="100%"
  59241. BORDER="0"
  59242. CELLPADDING="0"
  59243. CELLSPACING="0"
  59244. CLASS="EXAMPLE"
  59245. ><TR
  59246. ><TD
  59247. ><DIV
  59248. CLASS="example"
  59249. ><A
  59250. NAME="AEN10432"
  59251. ></A
  59252. ><P
  59253. ><B
  59254. >Example 1. <B
  59255. CLASS="function"
  59256. >array_uintersect_assoc()</B
  59257. > example</B
  59258. ></P
  59259. ><TABLE
  59260. BORDER="0"
  59261. BGCOLOR="#E0E0E0"
  59262. CELLPADDING="5"
  59263. ><TR
  59264. ><TD
  59265. ><PRE
  59266. CLASS="php"
  59267. ><?php
  59268. $array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
  59269. $array2 = array("a" => "GREEN", "B" => "brown", "yellow", "red");
  59270.  
  59271. print_r(array_uintersect_assoc($array1, $array2, "strcasecmp"));
  59272. ?></PRE
  59273. ></TD
  59274. ></TR
  59275. ></TABLE
  59276. ><P
  59277. >The above example will output:</P
  59278. ><TABLE
  59279. BORDER="0"
  59280. BGCOLOR="#E0E0E0"
  59281. CELLPADDING="5"
  59282. ><TR
  59283. ><TD
  59284. ><PRE
  59285. CLASS="screen"
  59286. >Array
  59287. (
  59288.     [a] => green
  59289. )</PRE
  59290. ></TD
  59291. ></TR
  59292. ></TABLE
  59293. ></DIV
  59294. ></TD
  59295. ></TR
  59296. ></TABLE
  59297. >
  59298.     </P
  59299. ><P
  59300. >      For comparison is used the user supplied callback function.
  59301.      It must return an integer less than, equal
  59302.      to, or greater than zero if the first argument is considered to
  59303.      be respectively less than, equal to, or greater than the
  59304.      second.
  59305.     </P
  59306. ><P
  59307. >      See also <A
  59308. HREF="#function.array-uintersect"
  59309. ><B
  59310. CLASS="function"
  59311. >array_uintersect()</B
  59312. ></A
  59313. >,
  59314.      <A
  59315. HREF="#function.array-intersect-assoc"
  59316. ><B
  59317. CLASS="function"
  59318. >array_intersect_assoc()</B
  59319. ></A
  59320. >,
  59321.      <A
  59322. HREF="#function.array-intersect-uassoc"
  59323. ><B
  59324. CLASS="function"
  59325. >array_intersect_uassoc()</B
  59326. ></A
  59327. > and
  59328.      <A
  59329. HREF="#function.array-uintersect-uassoc"
  59330. ><B
  59331. CLASS="function"
  59332. >array_uintersect_uassoc()</B
  59333. ></A
  59334. >.
  59335.     </P
  59336. ></DIV
  59337. ><H1
  59338. ><A
  59339. NAME="function.array-uintersect-uassoc"
  59340. ></A
  59341. >array_uintersect_uassoc</H1
  59342. ><DIV
  59343. CLASS="refnamediv"
  59344. ><A
  59345. NAME="AEN10445"
  59346. ></A
  59347. ><P
  59348. >    (PHP 5)</P
  59349. >array_uintersect_uassoc -- Computes the intersection of arrays with additional index check, compares data and indexes by a callback functions</DIV
  59350. ><DIV
  59351. CLASS="refsect1"
  59352. ><A
  59353. NAME="AEN10448"
  59354. ></A
  59355. ><H2
  59356. >Description</H2
  59357. >array <B
  59358. CLASS="methodname"
  59359. >array_uintersect_uassoc</B
  59360. > ( array array1, array array2 [, array ..., callback data_compare_func, callback key_compare_func])<BR
  59361. ></BR
  59362. ><P
  59363. >      <B
  59364. CLASS="function"
  59365. >array_uintersect_uassoc()</B
  59366. > returns an array
  59367.      containing all the values of <VAR
  59368. CLASS="parameter"
  59369. >array1</VAR
  59370. >
  59371.      that are present in all the arguments. Note that the keys are used in
  59372.      the comparison unlike in <A
  59373. HREF="#function.array-uintersect"
  59374. ><B
  59375. CLASS="function"
  59376. >array_uintersect()</B
  59377. ></A
  59378. >.
  59379.      Both the data and the indexes are compared by using a callback functions.
  59380.     </P
  59381. ><P
  59382. >      <TABLE
  59383. WIDTH="100%"
  59384. BORDER="0"
  59385. CELLPADDING="0"
  59386. CELLSPACING="0"
  59387. CLASS="EXAMPLE"
  59388. ><TR
  59389. ><TD
  59390. ><DIV
  59391. CLASS="example"
  59392. ><A
  59393. NAME="AEN10473"
  59394. ></A
  59395. ><P
  59396. ><B
  59397. >Example 1. <B
  59398. CLASS="function"
  59399. >array_uintersect_uassoc()</B
  59400. > example</B
  59401. ></P
  59402. ><TABLE
  59403. BORDER="0"
  59404. BGCOLOR="#E0E0E0"
  59405. CELLPADDING="5"
  59406. ><TR
  59407. ><TD
  59408. ><PRE
  59409. CLASS="php"
  59410. ><?php
  59411. $array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
  59412. $array2 = array("a" => "GREEN", "B" => "brown", "yellow", "red");
  59413.  
  59414. print_r(array_uintersect_uassoc($array1, $array2, "strcasecmp", "strcasecmp"));
  59415. ?></PRE
  59416. ></TD
  59417. ></TR
  59418. ></TABLE
  59419. ><P
  59420. >The above example will output:</P
  59421. ><TABLE
  59422. BORDER="0"
  59423. BGCOLOR="#E0E0E0"
  59424. CELLPADDING="5"
  59425. ><TR
  59426. ><TD
  59427. ><PRE
  59428. CLASS="screen"
  59429. >Array
  59430. (
  59431.     [a] => green
  59432.     [b] => brown
  59433. )</PRE
  59434. ></TD
  59435. ></TR
  59436. ></TABLE
  59437. ></DIV
  59438. ></TD
  59439. ></TR
  59440. ></TABLE
  59441. >
  59442.     </P
  59443. ><P
  59444. >      For comparison is used the user supplied callback function.
  59445.      It must return an integer less than, equal
  59446.      to, or greater than zero if the first argument is considered to
  59447.      be respectively less than, equal to, or greater than the
  59448.      second.
  59449.     </P
  59450. ><P
  59451. >      See also <A
  59452. HREF="#function.array-uintersect"
  59453. ><B
  59454. CLASS="function"
  59455. >array_uintersect()</B
  59456. ></A
  59457. >,
  59458.      <A
  59459. HREF="#function.array-intersect-assoc"
  59460. ><B
  59461. CLASS="function"
  59462. >array_intersect_assoc()</B
  59463. ></A
  59464. >,
  59465.      <A
  59466. HREF="#function.array-intersect-uassoc"
  59467. ><B
  59468. CLASS="function"
  59469. >array_intersect_uassoc()</B
  59470. ></A
  59471. > and
  59472.      <A
  59473. HREF="#function.array-uintersect-assoc"
  59474. ><B
  59475. CLASS="function"
  59476. >array_uintersect_assoc()</B
  59477. ></A
  59478. >.
  59479.     </P
  59480. ></DIV
  59481. ><H1
  59482. ><A
  59483. NAME="function.array-uintersect"
  59484. ></A
  59485. >array_uintersect</H1
  59486. ><DIV
  59487. CLASS="refnamediv"
  59488. ><A
  59489. NAME="AEN10486"
  59490. ></A
  59491. ><P
  59492. >    (PHP 5)</P
  59493. >array_uintersect -- Computes the intersection of arrays, compares data by a callback function</DIV
  59494. ><DIV
  59495. CLASS="refsect1"
  59496. ><A
  59497. NAME="AEN10489"
  59498. ></A
  59499. ><H2
  59500. >Description</H2
  59501. >array <B
  59502. CLASS="methodname"
  59503. >array_uintersect</B
  59504. > ( array array1, array array2 [, array ..., callback data_compare_func])<BR
  59505. ></BR
  59506. ><P
  59507. >      <B
  59508. CLASS="function"
  59509. >array_uintersect()</B
  59510. > returns an array
  59511.      containing all the values of <VAR
  59512. CLASS="parameter"
  59513. >array1</VAR
  59514. >
  59515.      that are present in all the arguments.
  59516.      The data is compared by using a callback function.
  59517.     </P
  59518. ><P
  59519. >      <TABLE
  59520. WIDTH="100%"
  59521. BORDER="0"
  59522. CELLPADDING="0"
  59523. CELLSPACING="0"
  59524. CLASS="EXAMPLE"
  59525. ><TR
  59526. ><TD
  59527. ><DIV
  59528. CLASS="example"
  59529. ><A
  59530. NAME="AEN10510"
  59531. ></A
  59532. ><P
  59533. ><B
  59534. >Example 1. <B
  59535. CLASS="function"
  59536. >array_uintersect()</B
  59537. > example</B
  59538. ></P
  59539. ><TABLE
  59540. BORDER="0"
  59541. BGCOLOR="#E0E0E0"
  59542. CELLPADDING="5"
  59543. ><TR
  59544. ><TD
  59545. ><PRE
  59546. CLASS="php"
  59547. ><?php
  59548. $array1 = array("a" => "green", "b" => "brown", "c" => "blue", "red");
  59549. $array2 = array("a" => "GREEN", "B" => "brown", "yellow", "red");
  59550.  
  59551. print_r(array_uintersect($array1, $array2, "strcasecmp"));
  59552. ?></PRE
  59553. ></TD
  59554. ></TR
  59555. ></TABLE
  59556. ><P
  59557. >The above example will output:</P
  59558. ><TABLE
  59559. BORDER="0"
  59560. BGCOLOR="#E0E0E0"
  59561. CELLPADDING="5"
  59562. ><TR
  59563. ><TD
  59564. ><PRE
  59565. CLASS="screen"
  59566. >Array
  59567. (
  59568.     [a] => green
  59569.     [b] => brown
  59570.     [0] => red
  59571. )</PRE
  59572. ></TD
  59573. ></TR
  59574. ></TABLE
  59575. ></DIV
  59576. ></TD
  59577. ></TR
  59578. ></TABLE
  59579. >
  59580.     </P
  59581. ><P
  59582. >      For comparison is used the user supplied callback function.
  59583.      It must return an integer less than, equal
  59584.      to, or greater than zero if the first argument is considered to
  59585.      be respectively less than, equal to, or greater than the
  59586.      second.
  59587.     </P
  59588. ><P
  59589. >      See also <A
  59590. HREF="#function.array-intersect"
  59591. ><B
  59592. CLASS="function"
  59593. >array_intersect()</B
  59594. ></A
  59595. >,
  59596.      <A
  59597. HREF="#function.array-uintersect-assoc"
  59598. ><B
  59599. CLASS="function"
  59600. >array_uintersect_assoc()</B
  59601. ></A
  59602. >,
  59603.      <A
  59604. HREF="#function.array-intersect-uassoc"
  59605. ><B
  59606. CLASS="function"
  59607. >array_intersect_uassoc()</B
  59608. ></A
  59609. > and
  59610.      <A
  59611. HREF="#function.array-uintersect-uassoc"
  59612. ><B
  59613. CLASS="function"
  59614. >array_uintersect_uassoc()</B
  59615. ></A
  59616. >.
  59617.     </P
  59618. ></DIV
  59619. ><H1
  59620. ><A
  59621. NAME="function.array-unique"
  59622. ></A
  59623. >array_unique</H1
  59624. ><DIV
  59625. CLASS="refnamediv"
  59626. ><A
  59627. NAME="AEN10523"
  59628. ></A
  59629. ><P
  59630. >    (PHP 4 >= 4.0.1, PHP 5)</P
  59631. >array_unique -- Removes duplicate values from an array</DIV
  59632. ><DIV
  59633. CLASS="refsect1"
  59634. ><A
  59635. NAME="AEN10526"
  59636. ></A
  59637. ><H2
  59638. >Description</H2
  59639. >array <B
  59640. CLASS="methodname"
  59641. >array_unique</B
  59642. > ( array array)<BR
  59643. ></BR
  59644. ><P
  59645. >      <B
  59646. CLASS="function"
  59647. >array_unique()</B
  59648. > takes input
  59649.      <VAR
  59650. CLASS="parameter"
  59651. >array</VAR
  59652. > and returns a new array
  59653.      without duplicate values.
  59654.     </P
  59655. ><P
  59656. >      Note that keys are preserved. <B
  59657. CLASS="function"
  59658. >array_unique()</B
  59659. > sorts
  59660.      the values treated as string at first, then will keep the first key
  59661.      encountered for every value, and ignore all following keys. It does not
  59662.      mean that the key of the first related value from the unsorted
  59663.      <VAR
  59664. CLASS="parameter"
  59665. >array</VAR
  59666. > will be kept.
  59667.     </P
  59668. ><DIV
  59669. CLASS="note"
  59670. ><BLOCKQUOTE
  59671. CLASS="note"
  59672. ><P
  59673. ><B
  59674. >Note: </B
  59675. >
  59676.       Two elements are considered equal if and only if
  59677.       <VAR
  59678. CLASS="literal"
  59679. >(string) $elem1 === (string) $elem2</VAR
  59680. >. In words:
  59681.       when the string representation is the same.
  59682.      </P
  59683. ><P
  59684. >       The first element will be used.
  59685.      </P
  59686. ></BLOCKQUOTE
  59687. ></DIV
  59688. ><P
  59689. >      <TABLE
  59690. WIDTH="100%"
  59691. BORDER="0"
  59692. CELLPADDING="0"
  59693. CELLSPACING="0"
  59694. CLASS="EXAMPLE"
  59695. ><TR
  59696. ><TD
  59697. ><DIV
  59698. CLASS="example"
  59699. ><A
  59700. NAME="AEN10545"
  59701. ></A
  59702. ><P
  59703. ><B
  59704. >Example 1. <B
  59705. CLASS="function"
  59706. >array_unique()</B
  59707. > example</B
  59708. ></P
  59709. ><TABLE
  59710. BORDER="0"
  59711. BGCOLOR="#E0E0E0"
  59712. CELLPADDING="5"
  59713. ><TR
  59714. ><TD
  59715. ><PRE
  59716. CLASS="php"
  59717. ><?php
  59718. $input = array("a" => "green", "red", "b" => "green", "blue", "red");
  59719. $result = array_unique($input);
  59720. print_r($result);
  59721. ?></PRE
  59722. ></TD
  59723. ></TR
  59724. ></TABLE
  59725. ><P
  59726. >The above example will output:</P
  59727. ><TABLE
  59728. BORDER="0"
  59729. BGCOLOR="#E0E0E0"
  59730. CELLPADDING="5"
  59731. ><TR
  59732. ><TD
  59733. ><PRE
  59734. CLASS="php"
  59735. >Array
  59736. (
  59737.     [a] => green
  59738.     [0] => red
  59739.     [1] => blue
  59740. )</PRE
  59741. ></TD
  59742. ></TR
  59743. ></TABLE
  59744. ></DIV
  59745. ></TD
  59746. ></TR
  59747. ></TABLE
  59748. >
  59749.     </P
  59750. ><P
  59751. >      <TABLE
  59752. WIDTH="100%"
  59753. BORDER="0"
  59754. CELLPADDING="0"
  59755. CELLSPACING="0"
  59756. CLASS="EXAMPLE"
  59757. ><TR
  59758. ><TD
  59759. ><DIV
  59760. CLASS="example"
  59761. ><A
  59762. NAME="AEN10552"
  59763. ></A
  59764. ><P
  59765. ><B
  59766. >Example 2. <B
  59767. CLASS="function"
  59768. >array_unique()</B
  59769. > and types</B
  59770. ></P
  59771. ><TABLE
  59772. BORDER="0"
  59773. BGCOLOR="#E0E0E0"
  59774. CELLPADDING="5"
  59775. ><TR
  59776. ><TD
  59777. ><PRE
  59778. CLASS="php"
  59779. ><?php
  59780. $input = array(4, "4", "3", 4, 3, "3");
  59781. $result = array_unique($input);
  59782. var_dump($result);
  59783. ?></PRE
  59784. ></TD
  59785. ></TR
  59786. ></TABLE
  59787. ><P
  59788. >The above example will output:</P
  59789. ><TABLE
  59790. BORDER="0"
  59791. BGCOLOR="#E0E0E0"
  59792. CELLPADDING="5"
  59793. ><TR
  59794. ><TD
  59795. ><PRE
  59796. CLASS="php"
  59797. >array(2) {
  59798.   [0] => int(4)
  59799.   [2] => string(1) "3"
  59800. }</PRE
  59801. ></TD
  59802. ></TR
  59803. ></TABLE
  59804. ></DIV
  59805. ></TD
  59806. ></TR
  59807. ></TABLE
  59808. >
  59809.     </P
  59810. ></DIV
  59811. ><H1
  59812. ><A
  59813. NAME="function.array-unshift"
  59814. ></A
  59815. >array_unshift</H1
  59816. ><DIV
  59817. CLASS="refnamediv"
  59818. ><A
  59819. NAME="AEN10559"
  59820. ></A
  59821. ><P
  59822. >    (PHP 4 , PHP 5)</P
  59823. >array_unshift -- 
  59824.      Prepend one or more elements to the beginning of an array
  59825.     </DIV
  59826. ><DIV
  59827. CLASS="refsect1"
  59828. ><A
  59829. NAME="AEN10562"
  59830. ></A
  59831. ><H2
  59832. >Description</H2
  59833. >int <B
  59834. CLASS="methodname"
  59835. >array_unshift</B
  59836. > ( array &array, mixed var [, mixed ...])<BR
  59837. ></BR
  59838. ><P
  59839. >      <B
  59840. CLASS="function"
  59841. >array_unshift()</B
  59842. > prepends passed elements to
  59843.      the front of the <VAR
  59844. CLASS="parameter"
  59845. >array</VAR
  59846. >. Note that the list
  59847.      of elements is prepended as a whole, so that the prepended
  59848.      elements stay in the same order.  All numerical array keys will be 
  59849.      modified to start counting from zero while literal keys won't be touched. 
  59850.     </P
  59851. ><P
  59852. >      Returns the new number of elements in the
  59853.      <VAR
  59854. CLASS="parameter"
  59855. >array</VAR
  59856. >.
  59857.     </P
  59858. ><P
  59859. >      <TABLE
  59860. WIDTH="100%"
  59861. BORDER="0"
  59862. CELLPADDING="0"
  59863. CELLSPACING="0"
  59864. CLASS="EXAMPLE"
  59865. ><TR
  59866. ><TD
  59867. ><DIV
  59868. CLASS="example"
  59869. ><A
  59870. NAME="AEN10582"
  59871. ></A
  59872. ><P
  59873. ><B
  59874. >Example 1. <B
  59875. CLASS="function"
  59876. >array_unshift()</B
  59877. > example</B
  59878. ></P
  59879. ><TABLE
  59880. BORDER="0"
  59881. BGCOLOR="#E0E0E0"
  59882. CELLPADDING="5"
  59883. ><TR
  59884. ><TD
  59885. ><PRE
  59886. CLASS="php"
  59887. ><?php
  59888. $queue = array("orange", "banana");
  59889. array_unshift($queue, "apple", "raspberry");
  59890. ?></PRE
  59891. ></TD
  59892. ></TR
  59893. ></TABLE
  59894. ><P
  59895. >        This would result in <VAR
  59896. CLASS="varname"
  59897. >$queue</VAR
  59898. > having the
  59899.        following elements:
  59900.       </P
  59901. ><TABLE
  59902. BORDER="0"
  59903. BGCOLOR="#E0E0E0"
  59904. CELLPADDING="5"
  59905. ><TR
  59906. ><TD
  59907. ><PRE
  59908. CLASS="php"
  59909. >Array
  59910. (
  59911.     [0] => apple
  59912.     [1] => raspberry
  59913.     [2] => orange
  59914.     [3] => banana
  59915. )</PRE
  59916. ></TD
  59917. ></TR
  59918. ></TABLE
  59919. ></DIV
  59920. ></TD
  59921. ></TR
  59922. ></TABLE
  59923. >
  59924.     </P
  59925. ><P
  59926. >      See also <A
  59927. HREF="#function.array-shift"
  59928. ><B
  59929. CLASS="function"
  59930. >array_shift()</B
  59931. ></A
  59932. >,
  59933.      <A
  59934. HREF="#function.array