Cómo comprender la documentacion de php

[juanito1712]

Hace tiempo que empecé a aventurarme con esto de la programación y ahora ya me aclaro bastante con las documentaciones, pero al principio las abría y me parecían un poco a chino así que espero que os resulte útil mi primera colaboración a los que estáis empezando con esto


¿Que son las documentaciones de un lenguaje de programación?
Pues la documentación para ti debe ser como una biblia para un católico, debes consultarla cuando tengas dudas y ojearla cuando tengas tiempo libre para ver que te encuentras.
Entre otras cosas no es mas que la biblioteca de funciones que posee un lenguaje de programación y en caso de la documentación de php trae muy buenos ejemplos.

Asi que cuando os digan que mireis la documentacion no le temais, menos aun si han tenido la molestia de pasaros una página de la documentación en concreto.

Vamos a mirar una página cualquiera para ver que hay ahi.
http://php.net/manual/es/function.mail.php
Ahora trabajaremos a caballo entre esa página y este post así que no la cierres

Esta página de la documentación está explicando una función en concreto y puedes ver varias secciones en la página
Descripcion-Luego me metere mas a fondo con eso pero por ahora es ya no un ejemplo, sino la representacion de la funcion con todos los párametros posibles para ella

Parámetros-Antes he dicho "sino la representacion de la funcion con todos los párametros posibles para ella" pues ahora te desglosan y explican mas a fondo los parámetros de la funcion

Valores devueltos-En este caso a parte de enviar el mail no esperamos ninguna respuesta mas alla de true o false para saber si el uso de la funcion ha sido correcto, pero bueno ahi te dicen los valores que puede devolverte la funcion, en el siguiente caso http://php.net/manual/es/function.explode.php los valores devueltos son algo mas elaborados.

Historial de cambios-Quizás copies una función de algún post o descargues un script y la funcion que tienes no es exactamente igual a la que te muestra la documentacion, ahi puedes consultar si ese cambio es debido a alguna modificacion de la funcion o simplemente porque la llamada está mal realizada

Ejemplos-Esto no hace falta mucho explicarlo ¿no?

Notas-Notas de interes para la funcion en concreto, es conveniente leerlas porque por ejemplo en esta nota nos dice algo como

Es importante indicar que la función mail() no es conveniente para grandes volúmenes de correo en bucle. Esta función abre y cierra un socket SMTP para cada correo, algo que no es muy eficiente.

Para enviar una gran cantidad de correo, ver los paquetes » PEAR::Mail y » PEAR::Mail_Queue.

Cosa que resulta un apunte muy importante

Ver tambien- pues otras páginas relacionadas a la funcion en concreto, en un principio no es necesario para utilizarla pero por ejemplo en esta página nos recomiendan el mail_queue para los mails masivos, pues ya se han tomado la molestia de vincularnos esa página para que no tengamos pegas

Ahora nos metemos con la seccion que al menos a mi mas extraña me parecia, en la descripcion de la funcion podemos ver esto

bool mail ( string $to , string $subject , string $message [, string $additional_headers [, string $additional_parameters ]] )

Es un poco... "demasiada información yo solo quiero ver como funciona" ¿verdad? lo malo es que así no sabrás las posibilidades de la función en concreto simplemente, te servirá para hacer lo que pretendes en ese momento, pero mirando la documentación te enterarás de todo lo que es capaz de hacer y aprenderás que es lo bueno ;)

Vamos a desglosarla
bool ¿que pinta ahi? pero si no se gasta, y en parte tienes razon, ese bool no se pone simplemente es el tipo de variable que nos devolverá la funcion.

luego pasamos a mail, simplemente la llamada de la funcion

vemos muchas cosas y ademas entre paréntesis y corchetes que nos despistan, pues poco a poco...
independientemente de los corchetes los valores están separados por comas
string $to , string $subject ,.... y envueltos por paréntesis, esos son los parámetros que acepta esa funcion.
Nos indican el tipo de variable que debe haber ahi y un nombre para identificarla y hacerle referencia en el resto de la documentación

ahi por ejemplo tenemos un "string $to," nos dicen que en ese lugar va una variable tipo string, no vale un entero, no vale un boleano, no vale un fichero... la funcion quiere un string y le ponen un nombre (por ponerle algo representativo) con el cual en la seccion parámetros puedes ver

to
Receptor o receptores del correo.

Es formato de este string debe cumplir con » RFC 2822. Algunos ejemplos son:

[email protected]
[email protected], [email protected]
Usuario <[email protected]>
Usuario <[email protected]>, Otro usuario <[email protected]>

ya nos concretan ademas de que debe de ser, como debe de ser y de una forma muy clara y sencilla, además si eres algo curioso ya te dan pistas sobre que podrias googlear RFC 2822 a ver que es eso...


"pero hay corchetes ademas de los paréntesis"
Exacto pero fíjate que si quitases los corchetes los parámetros seguirían manteniendo la estructura de
tipo nombre coma tipo nombre coma el corchete simplemente nos indica que es un parámetro opcional, podemos ponerlo o no segun nos interese, pero todo los demas que está entre paréntesis pero no entre corchetes son OBLIGATORIOS si no los pones, la llamada a la función nos dará un bonito mensaje de error.

¿Y eso de corchetes dentro de corchetes?
Pues son lo mismo solo que dependen del parámetro que los rodee

en este caso string $additional_parameters es un parámetro opcional pero no tendria ningun sentido incluirlo si no le hubiésemos indicado antes string $additional_headers

y ya está, no es corto pero con paciencia, un poco de decisión y un poco de base en vocabulario en lenguajes de programación para saber que es una función que es un parámetro que es una variable o que diferencia hay entre un array repleto de números o un entero podrás amar las documentaciones ;)