[Sync-En] curl: add POST examples

reference/curl/examples.xml

@@ -1,22 +1,87 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: fc9a0a8b29a7a099998bdd71fe5350a10b18fe62 Maintainer: Marqitos Status: ready -->
+<!-- EN-Revision: e7c6a2f6847c3a8c9fec6ba588f235ccdcf6f3a5 Maintainer: Marqitos Status: ready -->
 <!-- Reviewed: no -->
 
 <chapter xml:id="curl.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  &reftitle.examples;
  <section xml:id="curl.examples-basic">
-  <title>Ejemplo con curl</title>
-  <para>
+  <title>Ejemplos básicos con curl</title>
+  <simpara>
    Una vez compilado PHP con soporte para cURL, puede empezar a usar
    las funciones cURL. La idea básica detrás de las funciones cURL es
    que se inicializa una sesión cURL usando
    <function>curl_init</function>, luego pueden definirse todas
    las opciones para la transferencia con la función <function>curl_setopt</function>,
    y finalmente, puede ejecutarse la sesión con
    <function>curl_exec</function>.
-   A continuación se muestra un ejemplo que utiliza las funciones cURL para recuperar la página de inicio del sitio
-   example.com en un fichero:
+  </simpara>
+  <para>
+   A continuación se muestra un ejemplo sencillo que utiliza las funciones cURL
+   para enviar una petición POST:
+   <example>
+    <title>Uso del módulo cURL de PHP para enviar una petición POST</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$data = ['foo' => 'bar', 'baz' => 48];
+$url = "http://www.example.com/handler.php";
+
+$ch = curl_init($url);
+
+// indicar a CURL que devuelva la respuesta en lugar de enviarla a la salida estándar
+curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+
+// definir los datos POST, el método correspondiente y las cabeceras
+curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
+
+// enviar la petición y obtener la respuesta
+$response = curl_exec($ch);
+
+if(curl_error($ch)) {
+    // gestionar el error, o simplemente
+    throw new RuntimeException(curl_error($ch));
+}
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   Otro ejemplo que utiliza las funciones cURL para enviar una petición POST
+   con JSON en bruto:
+   <example>
+    <title>Uso del módulo cURL de PHP para enviar una petición POST con JSON</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$post_data = ['foo' => 'bar', 'baz' => 48];
+$url = "http://www.example.com/api/endpoint";
+
+$ch = curl_init($url);
+
+// indicar a CURL que devuelva la respuesta en lugar de enviarla a la salida estándar
+curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+
+// definir los datos POST y el método correspondiente
+curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post_data));
+
+// definir la cabecera necesaria
+curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
+
+// enviar la petición y obtener la respuesta
+$response = curl_exec($ch);
+
+if(curl_error($ch)) {
+    // gestionar el error, o simplemente
+    throw new RuntimeException(curl_error($ch));
+}
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   A continuación se muestra otro ejemplo que utiliza las funciones cURL para recuperar
+   la página de inicio del sitio example.com en un fichero:
    <example>
     <title>Uso del módulo cURL para recuperar la página de inicio de example.com</title>
     <programlisting role="php">
@@ -34,7 +99,6 @@ if(curl_error($ch)) {
     fwrite($fp, curl_error($ch));
 }
 fclose($fp);
-?>
 ]]>
     </programlisting>
    </example>