Better php doc in the code

Embed/Adapters/Adapter.php

@@ -41,8 +41,17 @@ abstract class Adapter
         'embedlyKey' => null
     );
 
+    /**
+     * Initializes all providers used in this adapter (oembed, opengraph, etc)
+     * 
+     * @param Request $request
+     */
     abstract protected function initProviders (Request $request);
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function __construct(Request $request, array $options = null)
     {
         if ($options !== null) {
@@ -56,6 +65,15 @@ public function __construct(Request $request, array $options = null)
         }
     }
 
+
+    /**
+     * Magic method to execute and save the url data.
+     * For example, on call $this->title, executes $this->getTitle()
+     * 
+     * @param string $name
+     * 
+     * @return mixed
+     */
     public function __get($name)
     {
         $method = 'get'.$name;
@@ -65,6 +83,15 @@ public function __get($name)
         }
     }
 
+
+    /**
+     * Search and returns data from the providers
+     * 
+     * @param string  $name        The data name (title, description, image, etc)
+     * @param boolean $returnFirst If it's true, returns the first value found, else returns the most popular value
+     * 
+     * @return mixed
+     */
     public function getFromProviders($name, $returnFirst = true)
     {
         $method = 'get'.$name;
@@ -92,6 +119,15 @@ public function getFromProviders($name, $returnFirst = true)
         return $current;
     }
 
+
+    /**
+     * Search and returns url type data from the providers (image, providerIcon, providerUrl, etc)
+     * If the url found is relative, transforms it to absolute
+     * 
+     * @param string $name The data name
+     * 
+     * @return null|string
+     */
     public function getUrlFromProviders($name)
     {
         $method = 'get'.$name;
@@ -103,36 +139,64 @@ public function getUrlFromProviders($name)
         }
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getTitle()
     {
         return $this->getFromProviders('title') ?: $this->request->getUrl();
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getDescription()
     {
         return $this->getFromProviders('description');
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getUrl()
     {
         return $this->getUrlFromProviders('url') ?: $this->request->getUrl();
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getSource()
     {
         return $this->getUrlFromProviders('source');
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getAuthorName()
     {
         return $this->getFromProviders('authorName');
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getAuthorUrl()
     {
         return $this->getUrlFromProviders('authorUrl');
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getAspectRatio()
     {
         $width = $this->width;
@@ -143,6 +207,10 @@ public function getAspectRatio()
         }
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getImage()
     {
         foreach ($this->images as $src) {
@@ -165,6 +233,10 @@ public function getImage()
         }
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getProviderIcon()
     {
         if ($this->options['getBiggerIcon']) {
@@ -186,31 +258,55 @@ public function getProviderIcon()
         }
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getProviderName()
     {
         return $this->getFromProviders('providerName') ?: $this->request->getDomain();
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getProviderUrl()
     {
         return $this->getUrlFromProviders('providerUrl') ?: ($this->request->getScheme().'://'.$this->request->getDomain(true));
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getImageWidth()
     {
         return null;
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getImageHeight()
     {
         return null;
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getWidth()
     {
         return $this->getFromProviders('width');
     }
 
+
+    /**
+     * {@inheritDoc}
+     */
     public function getHeight()
     {
         return $this->getFromProviders('height');

Embed/Adapters/AdapterInterface.php

@@ -8,43 +8,179 @@
 
 interface AdapterInterface
 {
+    /**
+     * Checks whether the request is valid to this Adapter
+     * 
+     * @param Request $request
+     * 
+     * @return boolean
+     */
     public static function check (Request $request);
 
+
+    /**
+     * Constructor.
+     * 
+     * @param Request    $request
+     * @param null|array $options
+     */
     public function __construct (Request $request, array $options = null);
 
+
+    /**
+     * Gets the title
+     * 
+     * @return string|null
+     */
     public function getTitle ();
 
+
+    /**
+     * Gets the description
+     * 
+     * @return string|null
+     */
     public function getDescription ();
 
+
+    /**
+     * Gets the type of the url
+     * The types are the same than the oEmbed types:
+     * video, photo, link, rich
+     * 
+     * @return string|null
+     */
     public function getType ();
 
+
+    /**
+     * Gets the source url (feed, api, etc)
+     * 
+     * @return string|null
+     */
     public function getSource ();
 
+
+    /**
+     * Gets the embed code
+     * 
+     * @return string|null
+     */
     public function getCode ();
 
+
+    /**
+     * Gets the canonical url
+     * 
+     * @return string|null
+     */
     public function getUrl ();
 
+
+    /**
+     * Gets the author name
+     * 
+     * @return string|null
+     */
     public function getAuthorName ();
 
+
+    /**
+     * Gets the author url
+     * 
+     * @return string|null
+     */
     public function getAuthorUrl ();
 
+
+    /**
+     * Gets all icon provider urls found
+     * 
+     * @return array
+     */
     public function getProviderIcons ();
 
+
+    /**
+     * Gets the best icon provider
+     * if $options['getBiggerIcon'] is true, returns the bigger image found
+     * else, returns the first found
+     * 
+     * @return string|null
+     */
     public function getProviderIcon ();
 
+
+    /**
+     * Gets the provider name
+     * 
+     * @return string|null
+     */
     public function getProviderName ();
 
+
+    /**
+     * Gets the provider url (usually the home url of the link)
+     * 
+     * @return string|null
+     */
     public function getProviderUrl ();
 
+
+    /**
+     * Gets all images found in the webpage
+     * 
+     * @return array
+     */
+    public function getImages ();
+
+
+    /**
+     * Gets the best image
+     * if $options['getBiggerImage'] is true, returns the biggest image
+     * 
+     * @return string|null
+     */
     public function getImage ();
 
+
+    /**
+     * Gets the image width
+     * 
+     * @return integer|null
+     */
     public function getImageWidth ();
 
+
+    /**
+     * Gets the image height
+     * 
+     * @return integer|null
+     */
     public function getImageHeight ();
 
+
+    /**
+     * Gets the width of the embedded widget
+     * 
+     * @return integer|null
+     */
     public function getWidth ();
 
+
+    /**
+     * Gets the height of the embedded widget
+     * 
+     * @return integer|null
+     */
     public function getHeight ();
 
+
+    /**
+     * Gets the aspect ratio of the embedded widget
+     * (useful to make it flexible)
+     * 
+     * @return float|null
+     */
     public function getAspectRatio ();
 }