php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #21970 Creating a new Tutorial section
Submitted: 2003-01-30 16:04 UTC Modified: 2010-01-17 14:54 UTC
Votes:19
Avg. Score:4.5 ± 1.0
Reproduced:15 of 17 (88.2%)
Same Version:8 (53.3%)
Same OS:11 (73.3%)
From: philip at cornado dot com Assigned:
Status: Suspended Package: Documentation problem
PHP Version: Irrelevant OS: *
Private report: No CVE-ID: None
View Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
If you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: philip at cornado dot com
New email:
PHP Version: OS:

 

 [2003-01-30 16:04 UTC] philip at cornado dot com
Topic: include_path (PHP_INI_ALL)

It seems that the include_path directive has been confusing some people lately so let's teach everyone how to use it.   This is a request for a tutorial ("tutorial.include-path") that explains the use include_path.  Topics include:

+ How to set it properly/effectivly using*:
  - ini_set() (PHP_INI_USER)
  - .htaccess (PHP_INI_PERDIR)
  - php.ini (PHP_INI_SYSTEM)
  - httpd.conf (PHP_INI_SYSTEM)

  See also: config.xml      : sec1 configuration.changes
            PHP_INI_* table : currently in ini_set() docs

  * Another need is an explanation of conf features 
    in terms of other web servers like IIS (i.e. 
    windows registry), but that's another topic.

+ It's meaning in relation to:
  - include/require
  - safe mode
  - open_basedir
  - allow_url_fopen  (filesystem/ini.xml)
  - streams
  - ini_get
  - readfile, file, etc. (mention other stuff that uses include_path)

+ Examples
+ Include all changes (when bugs|features were fixed|added)

This is both a report to gather confirmed facts as well as a reminder for us to eventually write it.  In otherwords, all documentation within the entire manual on this topic needs evaluating.

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2004-11-07 07:41 UTC] aidan@php.net
I think a new, broader tutorial section could encompass a lot of material that has been looking for a home.

The patterns page, a page about include_path, perhaps the magic quotes and register globals pages? I'd also like a section discussing basic query string mapping (?page=foo).

Thoughts?
 [2004-11-25 03:11 UTC] sean@php.net
+1 on the tutorial section
 [2004-11-25 11:39 UTC] techtonik@php.net
+1 from me on the tutorial
also tutorial on cmdline PHP usage would be great

 [2005-01-22 10:16 UTC] aidan@php.net
It seems we are happy enough to add the new section, the question is where?

Chapter I - Getting Started - Could be renamed to either "Tutorials", and Getting-Started the first tutorial in that section.

So far, the tutorial section could contain:
- include_path
- php5 patterns
- magic_quotes (info moved from security / faq)
- register_globals (info moved from security / faq)
- command line usage
?- black box design (foo.php?page=contact etc).
?- good sql / database practice (also moved from security section)



 [2005-01-22 10:17 UTC] aidan@php.net
It seems we are happy enough to add the new section, the question is where?

Chapter I - Getting Started - Could be renamed to either "Tutorials", and Getting-Started the first tutorial in that section.

So far, the tutorial section could contain:
- include_path
- php5 patterns
- magic_quotes (info moved from security / faq)
- register_globals (info moved from security / faq)
- command line usage
?- black box design (foo.php?page=contact etc).
?- good sql / database practice (also moved from security section)



 [2005-01-22 13:57 UTC] aj_gemmell at yahoo dot com
I suggest features.safe-mode should also be added to this (how it works, what it does [,when you should use it])

--GwaiLo
 [2005-01-22 21:39 UTC] derek@php.net
s/info moved from/info copied from/


We should not move anything from other sections that currently have a "home" just because a new tutorial is being added. Eg, the things in the security section need to stay there. We can either reiterate the points mentioned, or link to the chapters containing the information.
 [2005-01-23 08:19 UTC] aidan@php.net
I disagree. I think a lot of that content was added because there was no other good place for it.

It would be nice to get some feedback from Goba!
 [2005-01-23 08:23 UTC] derek@php.net
I believe we should rename Getting Started to Tutorials (or something similar and relevant), and move it below Language Reference. The introduction section of Getting Started should be moved to the beginning of the Language Reference section. This seems to fit best. Right now 'Getting Started' is an oddball.
 [2005-01-23 14:50 UTC] techtonik@php.net
No, getting started is for beginners and they should be able to get to this page as fast as possible by just clicking "next" link or by looking at Table of Contents. Being good attractor for newbies "Getting Started" should be located at the top of ToC and visible by default. "Language Reference" is too dull to reflect how clear and easy PHP is.

 [2005-01-23 15:09 UTC] goba@php.net
I think 'getting started' should be left alone, it is quite good for a beginner to start. If you look a bit closely at 'features' though, it is the exact place where tutorials are located already. We agreed on it before AFAIR that extension specific tutorials should go into their reference part, while broader scope tutorials or core tutorials should go into 'features'. Now we can rename it to 'PHP Programming Techniques' or something more flashy, but I think it is the right place to push tutorials into (except the getting started tutorial).

Derek: 'reference' should be very far from being confused with 'tutorial' IMHO!
 [2005-01-24 16:44 UTC] sean@php.net
I agree with both Anatoly & Goba, here.
- Getting started needs to be easily found by new developers.
- And ~"Techniques" is a good name for the section we envisioned as "Tutorials" they're programming (usually php-specific or web-specific) techniques.
- Perhaps a note should be dropped into the intro to "features/techniques" section that links to Getting Started.

S


 [2005-01-25 07:44 UTC] philip@php.net
Somewhere down the line this bug report got renamed so be sure it's not closed until include_path is properly (extensively) documented.

Not everything belongs in a tutorial...I agree with Goba on all points.
 [2005-09-09 08:28 UTC] aidan@php.net
Summarising the feedback,

* I think we've agreed "techniques" is the way to go in terms of naming the new section.

* I think getting-started will stay where it is.

* The new techniques section will be placed after the  security section.

* All the material in the features section will be incorporated into the techniques section.

And the following new sections will be created,

- techniques.include-path
See philip's original post.
Also, I notice a lot of questions regarding include_paths in included files, where the include path is relative to, getcwd, etc. This would make a nice addition to the include-path section.

- techniques.patterns
PHP 4 / 5 singleton + factory patterns

- techniques.magic-quotes
Info moved and aggregated from the security / faq

- techniques.register-globals
Info moved and aggregated from the security / faq

- techniques.command-line
All the information about running PHP from the CLI

?- techniques.databasing
general good database practices (also moved from security section)


So far I think everyone has agreed on these. The ones we're not too sure about being the tutorial-type sections. Perhaps these could be placed in a subsection of techniques called "design".


- techniques.design.black-box
Detailing the foo.php?page=contact design
 [2005-09-09 09:27 UTC] derek@php.net
Certainly techniques.patterns should be techniques.design.patterns?
 [2005-09-09 09:33 UTC] derek@php.net
Hmm, forgot about this in my last reply, but if we're adding "common techniques" and such we should add a techniques.design.pagination, as it's something extremely common that I see a lot of new programmers asking about.
 [2005-09-09 11:59 UTC] techtonik@php.net
>- techniques.patterns
>PHP 4 / 5 singleton + factory patterns

Before you'll do such an evil thing consider writing an article "patterns misusing borders". There was once a good article about that on phppatterns, but the site seems to be closed. And consider new chapters like "Debugging PHP" and "Debugging Patterns" first. My IMHO, but before patterns one should use project planning tools like rationale to avoid his mind wasting time doing coding for coding. Also consider alternative chapter "Framework approach" with OO, function-like and pattern-built framework problems overview. I know this is complicated, but these are questions every developer is interested in - not about what is patterns and how they cool. Patterns are good in reversed languages like Java and mostly for complex projects with complicated structure (observers). Without project planning and product development methodologies patterns are not maintanable.

>- techniques.magic-quotes
>Info moved and aggregated from the security / faq
>
>- techniques.register-globals
>Info moved and aggregated from the security / faq

No. Security features should be in securty section. Users should not read through all PHP manual and especially through patterns just to figure out how to secure their server.

>* All the material in the features section will be 
>incorporated into the techniques section.

I think there is clear distinction from "language feature" and "techniques of using language feature"

+ Using PHP in... 
...scripting (command line)
...scripting (application)
...integration (Java)
...integration (.NET)
...platform independent/dependent
...interfaces (smarty, GTK, plugins)
...enterprise
...PHP bussiness dictionary (like what is thin client, multitier arch and so on - the basics everybody is speaking about, but nobody wants to explain in common words)

Well, seems like all this info is subject to separate documentation pack - it can contain a lot of info and clutter search results for those newbies, who use PHP manual solely as reference to functions and PHP bugs.

 [2005-09-09 20:53 UTC] goba@php.net
Newbies don't use the manual for just reference purposes, it is quite on the contrary.
 [2007-02-26 09:22 UTC] philip@php.net
unassigned 
 [2008-11-10 14:42 UTC] kalle@php.net
Does Docbook have the elements that could create a tutorial section? I think a tutorial section globally and per extension reference would be great.
 [2010-01-17 14:54 UTC] bjori@php.net
Please use the mailinglist for discussions.
And please do not hijack bug reports.

Although I do agree that a FAQ/tutorial about include_path would be 
great it simply isn't a priority (this has been open for 7years..).

If there is a bug in the current documentations 
(http://no.php.net/manual/en/ini.core.php#ini.include-path) please open 
a new bug report.


 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Thu Dec 12 15:01:32 2024 UTC