как читать документацию

Документация, это такой текст, в котором описано что и как работает, в каких условиях и как этим пользоваться.
Найти документацию языка php можно на официальном сайте http://php.net нажав вверху кнопочку documentation. Документация там присутствует на нескольких языках. В том числе и Русском. Однако на русский переведено далеко не все. Все другие документации которые вы повстречаете на других сайтах это эта-же документация, которую предлагают скачать с php.net немного переоформленная другими цветами. Некоторые из них местами до-переведены авторами сайтов, но как показывает практика - легче было скопировать пару слов в словарь нежели сидеть несколько ночей искать ошибку в приложении.

Научиться работать с документацией это основной шаг в переходе к самостоятельному программированию и разработке. Документация это то, куда нужно в первую очередь обращаться за помощью если чего-то не знаешь. Именно благодаря документации ты почти не видишь тем на форуме созданных квалифицированными программистами, и вовсе не потому что они все знают. Просто потому что они знают где искать в первую очередь.


Структура документации

Что мы видим я описывать не буду. Ты и так это видишь. Обрати дополнительное внимание на то, что ссылки распределены древообразно, тоесть по категориям. Чаще всего в процессе работы нас будет интересовать раздел "Справочник Функций". Остальные будет достаточно прочесть один раз.


Справочник Функций

Все функции в справочнике также разделены по категориям среди которых к примеру Работа с изображениями, работа с файлами, дата и время, шифрование, базы данных и т.д. В каждой из этих категорий находятся несколько библиотек. Напомню что библиотекой называется набор функций. К примеру для работы с изображениями мы видим три библиотеки: GD, EXIF и ImageMagick . Каждая из этих библиотек содержит набор функций. Нажмем для примера GD.


Документация библиотеки

Для каждой библиотеки в документации описана её установка, требования и настройка. Для некоторых библиотек даже приведены примеры использования функций библиотеки. А самая важная часть это список функций.

В списке функций мы видим название функции и её предназначение. Здесь то самое место искать то, не знаю что. Если нужно узнать ширину картинки и ты не знаешь как это сделать, то в первую очередь стоит направиться именно здесь и в описании функций искать то, что нам надо. Искать можно очень простым способом. Нажать Ctrl + F и написать там width . Функции которые имеют какое нибудь отношение к ширине сразу всплывут перед глазами. Мне этого делать не понадобилось потому что первое что я увидел на высоте середины экрана оказалась функция getimagesize — Get the size of an image .
Получить размер изображения. Вроде бы как раз то, что мне нужно. Посмотрим с чем её едят.


getimagesize — Get the size of an image

В самом верху название функции и версии php в которых она доступна.
Далее мы видим 8 фиолетовых блоков: Описание; Список параметров; Возвращаемые значения; Ошибки/Исключения; Список изменений; Примеры; Примечания; Смотрите также.

Начнем по порядку. С картинками.
http://img10.imageshack.us/img10/9476/23219241.png
И так, функция описывается при помощи типа возвращаемого результата. Типы мы проходили в первой главе. Может стоит повторить ? Далее идет название функции
и в скобочках её аргументы. Так как главу о функциях мы уже прошли, то для тебя не секрет что функцию можно создавать и с необязательными параметрами. В квадратных скобочках в документации именно такие и указываются.

Так же для тебя не секрет что можно передавать переменные по ссылке. Тогда в функцию попадает не значение переменной а сама переменная, которую потом функция и меняет. Тоже самое в данном случае с переменной $imageinfo которая передается по ссылке и функция её изменяет в процессе работы.

Также там указаны типы переменных которыми должны быть аргументы. Если вы передадите другой тип данных, интерпретатор попробует его изменить на подходящий.
А еще полное описание функции и пару замечаний к ней в комплекте прилагаются, я их вырезал.

Дальше идет список параметров, который поймет даже самая светловолосая танкистка, если прочитает, где поясняется за что отвечает каждый из аргументов функции.

Далее мы видим такой раздел как Возвращаемое значение. В нем описывается в нашем конкретном случае что же будет населять возвращаемый функцией массив.

Раздел ошибок и исключений рассказывает что произойдет если к примеру функция попытается установить размер несуществующей картинки. Какого уровня будет эта ошибка.

Список изменений содержит нововведения и изменения которые перетерпела функция в процессе развития языка. Полезно пролистать и до туда, так как не мало обновлений встречаются между минорными версиями php между к примеру 5.29 и 5.3.

Пару примеров на закуску и примечания, а дальше две не менее важные составляющие этой документации. Первая в списке это "смотрите также".


Смотри также

Предположим что наша задача была установить тип нашего изображения(gif, jpeg, ..). Почитав документацию, мы бы выяснили что в массиве возвращаемом этой функцией есть такой элемент как тип. Но!, помимо типа эта функция возвращает еще массу разных данных, которые нам попросту не нужны. А значит она тратит много ресурсов, времени и памяти. Намного лучше было бы использовать функцию предназначенную под это конкретное действие и если такая функция есть - она обязательно будет в списке "смотри также".


Комментарии

Очень важная вещь в документации это комментарии к функциям. В комментариях специально для тебя (ведь не для себя же их писали авторы) находятся масса примеров использования функций, решения всех наиболее популярных задач, таких как наложении печати на картинки, генерация превьюшек в разделе GD и более.

Комментарии это то, куда нужно обращаться еще до того как появится желание пойти спросить на форуме как что-то сделать. Запомни это в первую очередь.

А вот что делать если не знаешь английского, спросишь ты. И тут мне остается посоветовать тебе только одно.. Отложи эту книжечку пока не надолго и учи Английский. Без него действительно никуда.


Еще один особенный сайт

Называется он google.com

Да. я знаю что ты о нем слышал.. А почему не пользуешься ? Я на 100% уверен что все, что может тебя интересовать на данном уровне освоение php уже давно изобретено, написано, исписано и десяток раз переписано. Там вполне можно найти решение на любую поставленную правильно задачу, найти примеры любого когда и найти ответ на любой ваш вопрос.


То, на чем все держится

Я так же рекомендую использовать документацию не только PHP.
Ведь дело в том, что PHP очень тесно связан с другими системами. Прежде всего, с платформой. Желательно хорошо знать ОС (операционную систему), на которой все устанавливается. И там - ты не поверишь - тоже есть документация! Тебе особенно повезло, если ты являешься обладателем FreeBSD или linux - система бодро рапортует по нужному тебе вопросу командой man. Так же есть замечательные люди, создавшие http://opennet.ru - даже на русском языке. Там всего есть что-нибудь интересное


Исполнитель - веб-вервер..

Затем, святая святых - веб-сервер. Чаще всего это Apache.
Так почему бы не задавать бесконечные вопросы о VirtualHost, mod_rewrite и т.п. , а пойти на http://apache.org и там все прочесть?


Быстрее, выше, сильнее...

Почти всегда хочется чего-то большего. И тебе хочется использовать БД. Ну, а где, как не на http://mysql.com прочитать о ней, и найти документацию - то, ради чего сей урок был написан? Будет очень полезно узнать там о функциях этой СУБД (конечно, это все относится только к MySQL, но при помощи универсальной ссылки http://google.com можно легко обнаружить официальные сайты других СУБД, как, скажем, Postgree или Oracle)

Авторы: valenok, EuGen