As Swagger documentation files tend to get real large und hard too read, splitting the config across multiple files might be a good idea.
With $ref you could do this quite easily.

For example you could reference a single config file per path like so:

swagger: "2.0"
basePath: "my-api/v1/"
info:
  version: "0.0.1"
  title: "my API"
tags:
  - name: "section1"
    description: "Some Section"
  - name: "section2"
    description: "Some other Section"

paths:

  ##section 1

  /section1/some/path:
    $ref: 'paths/section1_some_path.yml'

  /section1/some-other-path:
    $ref: 'paths/section1_some_other_path.yml'

Then have all actions for this path defined in a dedicated file like this:

paths/section1_some_path.yml:

post:
  tags:
  - "section1"
  parameters:
    ...

This really helped me managing larger documentation files, which otherwise tend to get quite hard to read.

As I moved the code to github this week, I wanted to give a quick overview of the project and its technical underlyings, just in case someone might be interested :)

As the title of this post might already suggest, its about selecting and layering loops from audiofiles hosted on soundcloud.com and thereby creating new music.

Those collections of layered loops are called a session. Sessions can be created anonymously by everyone and are auto-saved on every action. By distributing the URL of a session other users can join and every action is synced between all users in realtime.
(complete mayhem, indeed :)

The application is built with HTML5 and JS w/ jQuery using the soundcloud API on the client side and runs on node.js & mongoDB with express, socket.io and mongoose on the server side.

I basically started the project to find out if you could play multiple loops asynchronous and synced with low latency using the Web Audio API while collaboratively working together with multiple users in realtime. 

As that turned out to be not only possible but performed real nicely, the experiment then developed in somewhat of an application and finally got a name and a face.

There’s a whole lot of things i’d like to implement / refactor and do when i get some time on my hands, as

– adding a “record” feature to record, save and export created sessions as audiofiles

– rewriting the client side with backbone.js (as things got a bit messy …)

– adding some audio effects to the tracks

– write some tests

I’d appreciate any form of contribution as much as any questions or feedback on the project :)

Feel free to check out the live version at  http://mashcloud.net/ or the sources at https://github.com/gherkins/mashcloud

    Symfony\Component\Security\Core\SecurityContext|void         getSecurity()
    Symfony\Component\Security\Core\User\(Advanced)UserInterface getUser()
    Symfony\Component\HttpFoundation\Request|void                getRequest()
    Symfony\Component\HttpFoundation\Session|void                getSession()
    string                                                       getEnvironment()
    bool                                                         getDebug()

In Twig liegt der Container im “app”-Namespace, “Übersetzt” nach Twig heißt das ganze also:

    app.security
    app.user
    app.request
    app.session
    app.environment
    app.debug

Viel Spaß beim Templates-Bauen ;)

Mein Lieblingsthema ist ja zur Zeit der Dependency Injection Container. Und irgendwie stinkt mir die ganze Container-Konfiguration noch gewaltig. Meine kläglichen Versuche, selbst mal so was ähnliches wie eine brauchbare Autowiring-Implementierung herunterzubrechen, waren natürlich auch bzw. erst recht nicht der große Wurf – was vor allem daran lag, dass ich den Service Container und damit den ganzen Sinn und Zweck des Ganzen einfach mal wegrationalisiert hatte – Loose Coupling sieht natürlich anders aus, das sei den Kritikern zugestanden. Ich verteidige mich mal dadurch, dass ich eigentlich nur mal mit Mixins rumspielen wollte – da hab’ ich wohl die eine oder andere Begrifflichkeit durcheinander geworfen.

Aber um mal zu des Pudels Kern zu kommen: Ist es wirklich so geil, mit kilometerlangen XML-Dateien, ‘ner Menge Initialisierungscode und ohne mit der heißgeliebten Code-Completion in der IDE meiner Wahl ein Paradigma zu kaufen, das im speziellen Anwendungskontext – nicht im Framework-Kontext – eher selten Anwendung findet?

Es ist doch so: PHP bietet zwar mittlerweile eine vernünftige Reflection API, aber wenig (keine) Möglichkeiten, Code zur Compile- oder Runtime effizient zu injizieren (vorbei bspw. an der Sichtbarkeit, was für Property Injection aus meiner Sicht erforderlich wäre). Mit Handständen geht das mittels der Reflection API, noch fieser mit bspw. Runkit.

Somit ist – (natürlich nur aus meiner Sicht, was im Übrigen für den gesamten “Complaint” gilt – dabei wäre ich wirklich froh, berichtigt zu werden) jeder Versuch, die Konfiguration eines wie auch immer gearteten, auf PHP sitzenden, DIC mit Syntactic Sugar anzureichern, vergeblich. Und Syntactic Sugar ist dringend vonnöten, um das Zeug in der Praxis RAD-tauglich zu machen. Nehme ich PHP den RAD-Faktor, was bleibt denn dann noch übrig?

Symfony 2 behilft sich damit, einen DI-Container zu definieren und ihn als PHP-Code wegzucachen. Dieser hat dann Accessoren für alle definierten Services, Constructor-Injection ist durch Referenzierung in den Konfigurationsdateien möglich. Die Doku spricht zusätzlich von Setter- und Property-Injection, dazu konnte ich aber irgendwie keine dokumentierten Beispiele finden. Es gibt aber immerhin die Möglichkeit, Methoden in der Service-Klasse als Pre- oder Post-Initialization Interceptoren auszuführen.

Letztlich tut der Container, was er soll: Abhängigkeiten in beliebige Instanzen zu injizieren. Bei Bedarf auch gegen ein Interface, aber das ist letztlich aufgrund des Sprachentwurfs nur optional (Was impliziert, das man auf Kosten riesiger Flexibilität – die man nicht braucht – schnell mal riskiert, durch einen falsch konfigurierten DI-Container seine Anwendung kaputt zu machen).

Aber der Aufwand steht meiner Meinung nach noch in keinem Verhältnis zum Nutzen. Am Beispiel einer Controller Extension, die als Service definiert wird, möchte ich das mal demonstrieren. Die offizielle Symfony 2-Dokumentation sagt, dass

To keep things simple, Symfony2 by defaults does not require that controllers be defined as services. Furthermore Symfony2 injects the entire service container into your controller.

Das ist immerhin schon einmal eine Information. Das Standardverhalten ist also, dass ich automagisch eine Controllerklasse habe, die den Container kennt (Wie? Magisch? Ich dachte, Symfony 2 hat die Magie zugunsten transparentem Code und ständiger Kontrolle über jeden Aspekt des Core-Frameworks aufgegeben?). Dadurch, dass er ein ContainerAware Interface implementiert, kennt er auch einen Shortcut auf

$this->container->get('serviceid')

, nämlich

$this->get('serviceid');

. Um Bspw. ein Doctrine-Entity zu persistieren, reichen “ein paar codezeilen”:

     $em = $this->get('doctrine.orm.entity_manager');
     $em->???($myEntity);

Wie hieß die Methode da am Entity Manager jetzt nochmal? Das ist das erste Problem: Dadurch, dass alle Services anonym im Service Container herumdümpeln bzw. auf ihre Instanziierung warten, habe ich in meiner IDE keinerlei Code-Completion mehr. Um das wieder zu erreichen, muss ich entweder
– einen Accessor schreiben (getEntityManager()) und diesen mittels PHP-Doc type-hinten (annotieren) oder
– mindestens einen magischen Docblock davorsetzen, der genau *meiner* IDE die Möglichkeit gibt, den Variablentyp zu erraten (aber ggf. proprietär ist, d.h. in anderen IDEs nicht unbedingt funktionieren muss). Für die Netbeans IDE gibt es dafür bspw. das “vdoc“-Feature.

Das ganze setzt natürlich voraus, dass ich *weiß*, welches Interface der Service doctrine.orm.entity_manager implementiert bzw wie die konkrete Klasse (samt Namespace) desselben heißt. Und vorher muss ich auch noch wissen, wie überhaupt der *Servicename* des Entity Managers lautet.

Bin ich also komplett Ahnungslos, rufe ich erstmal ein Terminal auf, tippe sowas wie

$ app/console container:debug --show-private

ein und suche mir anschließend in der kilometerlangen Liste genau die Services zusammen, die ich brauche.

Dafür brauche ich als Framework-Newbie schonmal richtig tiefgehende Kenntnisse darüber, was ein DIC überhaupt ist, tut und zur Konfiguration erfordert.

Um also das, was “früher” ein

new Cart($color, $maxSpeed)->save()

war, zu erreichen, muss ich nun erstmal ganz schön viel Sport treiben (dieses Beispiel nur exemplarisch, es steht außer Frage, dass die Doctrine 2-Architektur wirklich klasse ist. Das Manko aus meiner Sicht ist die Integration in Sf2, nicht der ORM-Layer an sich.)

Möchte ich den Accessor der ContainerAware-Implementierung am Controller vermeiden und die Services “direkt” injizieren, muss ich ihn selbst als Service am DIC registrieren. Wie das funktioniert, würde den Rahmen sprengen, nur so viel: Der Aufwand steht aus meiner Sicht wieder in keinem Verhältnis zum Ergebnis. Allerdings habe ich damit den Vorteil, dass ich bspw. keine abstrakte Controllerklasse mehr zu erweitern habe – der Controller kann ein simples Popo sein. Dass es aber nicht zu simpel sein darf, zeigt bspw., das ich trotz alledem mindestens einen Constructor definieren muss, der eben alle benötigten Services aufnimmt und an Instanzvariablen bindet. Und das können einige sein – fängt an beim Templating, geht übers Formframework, ggf. den Entity-Manager, einen Mailer und was einem sonst noch so einfällt. Dabei wollten wir doch ab jetzt nur noch leichtgewichtige Controller haben?

Meiner Meinung nach liegt die Lösung der Malaise in zwei Alternativen: Man baut so lange Abstracts, die den ganzen Kram als Shortcuts bereitstellen (dann hätten wir bspw. wieder eine komplexe, abstrakte Kontrollerklasse, die mindestens alles kennt, was in Symfony 1 noch dem ApplicationContext gehörte) – womit wir unser Loose Coupling Pardigma wieder in den Schrank zu den übrigen Ideen stellen können, die im Nachgang irgendwie doch nicht funktionierten. Oder legt Autowiring drüber.

Flow 3 baut bspw. an einem DIC + Autowiring, der alle verwalteten Services durch eine Kombination der Analyse von Annotationen (also PHP-Doccomments) und Signaturen (Typehints) direkt an die erzeugten Instanzen bindet. Die Konfiguration scheint damit sehr viel leichtgewichtiger.

Grails (was so weit ich weiß auf der Spring IOC-Komponente sitzt) geht noch einen Schritt weiter und mappt Instanzvariablen durch reine Naming-Conventions: Wenn also eine Instanzvariable auf “Service” endet und es zur Eigenschaft “mailerService” einen passenden Service “mailer” gibt, wird dieser automagisch injiziert. Kein zusätzlicher Code noch Annotations vonnöten.

Ich wüsste aber nicht, wie man solche Features wirklich performanceneutral, effizient und stabil auf einer Plattform wie PHP aufsetzen könnte – dafür ist die Sprache einfach (noch) nicht weit genug.

Abschließend bleibt ein übler Nachgeschmack – und der Eindruck, dass man sich hier fatal an den XML-“Konfigurationswahnsinn” der entsprechenden Java-“Vorbilder” annähern möchte. Wo doch gerade in diesem Lager intensiv daran gearbeitet wird, genau davon abzurücken und Konfigurationen eben durch Konventionen zu ersetzen.

Was denkt ihr? Kann das ganze doch durch Routine punkten, sodass es durch ein wenig konkrete Projekterfahrung doch ganz leicht von der Hand geht? Wird der DIC im Tagesgeschäft schon intensiv benutzt, oder werden nur die Standardfunktionen des Frameworks verwendet und das Zeug “unter der Haube” doch lieber den Framework- und Bundle-Entwicklern überlassen? Ich bin wieder sehr gespannt auf Meinungen und Kritik…

Ein formaler Parameter einer Methode/Funktion ist immer optional, wenn er einen Initialwert zugewiesen bekommt (Fachausdruck “Polymorphie für Arme”). Nun kann es sein, dass eine Methode zwar optional ist, man den DefaultValue aber nicht abfragen darf. ReflectionParameter::getDefaulValue() würde in diesem Falle eine Exception werfen. Dies kann bspw. bei internen Funktionen/Methoden (auch der Default-Constructor ist eine “interne” Methode) der Fall sein. Also Vorsicht bei Verwendung von ReflectionParameter::isOptional(), besser nochmal via ReflectionParameter::isDefaultValueAvailable() prüfen, ob man an den Parameter wirklich dran darf, bevor man ihn sich via ReflectionParameter::getDefaultValue() holt.

Also anstatt zu schreiben:

class DefaultController {
  
  def mySuperService
  
  def index = {
   mySuperService = new MySuperService(params);
   mySuperService.getData()
  }
}

schreibe ich einfach

class DefaultController {
 
  def mySuperService
 
  def index = {
   mySuperService.getData()
  }
}

Gut, sieht jetzt nicht besonders spektakulär aus, doch wenn man weiß, dass mySuperService im Hintergrund (Stichwort “Spring Managed Bean”) automatisch instanziiert sowie an meinen Controller gebunden wurde und dass da prinzipiell noch viel mehr geht, ist das bereits ein ganz brauchbares Feature.

Natürlich ist die Injizierung per Naming-convention eine Grails-eigene Lösung (alles, was auf Service endet, ist ein Service und wird injiziert), um Konfigurationsarbeit zu sparen. Für gewöhnlich wird das Verhalten sogenanner “managed Beans” natürlich konfiguriert, entweder Java-typisch via XML-Konfigurationsdatei oder durch Annotationen.

Dabei kann wiederum java-typisch auch der “Scope” einer Bean bestimmt werden; hier bringt vor allem der “Singleton” bzw. Application Scope einen Vorteil gegenüber einer statuslosen PHP-Anwendung. Doch bereits die Fähigkeit, den Scope überhaupt fein granulieren zu können, setzt das ganze wieder von PHP-Gemurkse ala $_SESSION, $_REQUEST etc. ab.

Also egal wo und in welchem Kontext man Managed Beans, Enterprise Java Beans, Spring Beans (Die Unterschiede interessieren hier mal nicht die Bohne – ich könnte sie auch gar nicht qualifiziert erläutern) einsetzt – das IoC-Muster spart Code, vereinfacht Abhängigkeiten und sorgt für schlankere Konstruktoren – ist insgesamt also eine sehr mächtige Sache.

Was aber nicht heißt, dass so etwas generell nicht auch in meiner PHP-Anwendung funktionieren kann.

sfDependencyInjectionContainerPlugin

Dieses Plugin (http://www.symfony-project.org/plugins/sfDependencyInjectionContainerPlugin) leistet genau das: Es verwaltet entweder über eine in PHP formulierte DSL(hust), über XML oder eine symfony-typische .yml-Datei konfigurierte Abhängigkeiten. Das Plugin ist selbst nur ein Adapter, das die Symfony-Komponente DependencyInjection in ein Symfony 1.2 (und höher) Projekt integriert – in Symfony 2.0 wird DependencyInjection voraussichtlich Bestandteil des Systemkerns sein.

Zur Installation und Konfiguration des Plugins verweise ich auf die README-Datei. Trotzdem vielleicht der Hinweis, dass die Bibliotheken mit einem eigenen Autoloader daherkommen, daher empfehle ich, folgende Programm-Zeilen in eure ProjectConfiguration.class.php hinzuzufügen:

config/projectConfiguration.class.php

  require_once dirname(__FILE__) . '/../pfad/zur/DependencyInjection/Komponente/sfServiceContainerAutoloader.php';
  sfServiceContainerAutoloader::register();

Anders habe ich es nicht hinbekommen, zwar lässt sich durch eine config/autoload.yml die Laufzeit von Class Not Found-Fehlern befreien, aber das Symfony Command Line Interface geht dann trotzdem hops. Für einen Tipp, wie man’s eleganter hinkriegt, wäre ich dankbar.

Beispielsweise möchte ich den Nerdpress-RSS-Feed in meine Seite einbinden. Dazu baue ich einen Proxy, um bequem via AJAX auf das entfernte RSS-XML zugreifen zu können.
Diesen Proxy definiere ich als Service und injiziere ihn meine Symfony-Module:

config/services.yml:

services:
  NerdpressRssProxy:
    class: NerdpressRssProxy

Diese drei Zeilen reichen bereits aus, um meine Abhängigkeit zu definieren.

Nun implementiere ich die Service-Klasse:

lib/NerdpressRssProxy.php

class NerdpressRssProxy
{
  /**
   * @var sfFileCache
   */
  protected $cache;

  /**
   * @return sfFileCache
   */
  public function getCache()
  {
    if (null === $this->cache)
    {
      $this->cache = new sfFileCache(array('cache_dir' => sfConfig::get('sf_cache_dir')));
    }
    return $this->cache;
  }

  /**
   * @return string
   * @throws Exception
   */
  public function getEntries()
  {
    $cache = $this->getCache();

    sfContext::getInstance()->getConfiguration()->loadHelpers(array('Helper', 'Tag', 'Url', 'Text'));

    if(!($rss = $cache->get('nerdpress_rss')))
    {
      if(($rss = @file_get_contents('https://nerdpress.org/feed')))
      {
        $rss = auto_link_text($rss, 'all', array('class' => 'external'));

        $cache->set('nerdpress_rss', $rss, 3600);
      }
      else
      {
        throw new Exception('Rss feed could not be opened');
      }
    }
    return $rss;
  }
}

Die Methode getEntries() rufe ich nun in meinem Nerdpress-RSS-Modul auf, um die WebResponse zu befüllen:

apps/frontend/modules/rssProxy/actions/actions.class.php

class rssProxyActions extends sfActions
{
  public function preExecute()
  {
    $this->getResponse()->setContentType('application/rss+xml');
  }
  
  public function executeNerdpress(sfWebRequest $request)
  {
    try
    {
      // SERVICE HOLEN UND getEntries() AUFRUFEN
      $rss = $this->getService('NerdpressRssProxy')->getEntries();

      $this->getResponse()->setHttpHeader('Content-Length', mb_strlen($rss));
      $this->getResponse()->setContent($rss);
    }
    catch(Exception $e)
    {
      $this->forward404($e->getMessage());
    }
    return sfView::NONE;
  }
}

Das wars. Einfach, oder? Ingesamt 3 Zeilen yml-Konfiguration reichen, um Dependency Injection “the PHP way” zu realisieren, Symfony sei Dank. Natürlich ist nicht *ganz* so hübsch wie in der J2EE-Welt und sicherlich funktional noch weit davon entfernt. Aber ein Anfang ist gemacht, und wenn man seine Services erst einmal auf diese Art und Weise unter Kontrolle bringt, ist man vom Nutzen der Sache schnell überzeugt: Mit ein bisschen Disziplin gehören “Controller-Spaghettiwürste” nämlich der Vergangenheit an.

Bitte entschuldigt eventuell fehlerhafte oder unsaubere Beschreibungen der Begriffe “Bean”, “IoC”, JSF2 etc. Ich bitte explizit um Korrektur in Form von Kommentaren :)

(function($) {

  $('item').each(function() { $(arguments[1]).find('dc\:creator').[...]() } );

})(jQuery);

Dies entspricht wohl rein syntaktisch nicht ganz dem entsprechendem CSS3-Proposal (einzusehen unter http://www.w3.org/TR/css3-selectors/#typenmsp). Ich habe beide Möglichkeiten interessehalber auch einmal in einem aktuellen FF3.6 und Chromium getestet:

<style type="text/css">
/*<![CDATA[*/
  @namespace hanswurst url(https://www.meins.int)

  hanswurst|kaese
  {
    color: red;
  }
/*]]>*/
</style>
<hanswurst:kaese>
  Hanswurst liebt käse
</hanswurst:kaese>

Ergebnis: Naja, klappt nicht. Eventuell hat jemand eine Idee oder kann mich korrigieren?

Wozu es gut ist und wie man es benutzt,will ich im Folgenden kurz erläutern:

Im Prinzip dasseselbe wie fpassthru(), aber eben ohne dass PHP den auszuliefernden Datenstrom komplett in den Speicher laden muss. Somit verbindet X-Sendfile die beiden Vorteile, dass bspw. Zugriffsberechtigungen applikationsseitig via PHP geprüft werden können und dass die Response selbst ausschließlich durch den darunterliegenden Server (in dem Fall Apache 2) ausliefert wird (und PHP komplett umgeht).

Somit ist es möglich, das PHP-eigene memory_limit zu umgehen und auch riesige Dateien zum (PHP-geschützten) Download bereitzustellen.

Für den Apachen gibt es zur Unterstützung dieses Features mod_xsendfile. Das Modul ist leider nicht in den offiziellen Ubuntu-Paketquellen enthalten, und auch dotdeb konnte mir bei meiner Suche nicht weiterhelfen. Die Übersetzung + Installation via apxs2 läuft aber unter Ubuntu problemlos (apxs2 ist jeweils in den Paketen apache2-prefork-dev und apache2-threaded-dev enthalten). Standard unter Ubuntu oder generell Gnu/Linux sollte “Prefork” sein.

apxs -cia mod_xsendfile.c

kompiliert das Modul und installiert es nach /usr/lib/apache2/modules. Anschließend erstellt man eine neue Konfigurationsdatei unter /etc/apache2/mods-available/mod_xsendfile.load mit folgendem Inhalt:

LoadModule xsendfile_module /usr/lib/apache2/modules/mod_xsendfile.so
<Files *.php>
  XSendFile on
  XSendFileAllowAbove on
</Files>

Dann das Modul noch mit

$ a2enmod xsendfile

aktivieren.

So hats bei mir auf Anhieb funktioniert,  zu den einzelnen Einstellungsmöglichkeiten schaut man dann einfach nochmal in die Doku.

Das PHP-Script sieht dann exemplarisch folgendermaßen aus:

if($user->isAuthenticated())
{
  // Wir werden eine Binär-Datei ausgeben
  header('Content-type: application/octet-stream');

  // Es wird downloaded.pdf benannt
  header('Content-Disposition: attachment; filename="'.$file->getFilename().'"');
  header('Content-Length: ' . $file->getSize());
  // PASS X-SENDFILE-HEADER.
  header('X-Sendfile: ' . $file->getPathname());
}

Das war einfach, oder?

Die Syntax ist mal denkbar einfach, denn das ganze beschränkt sich auf eine einzige Methode, nämlich:

yqlgeo.get(what,callback)

Damit geht neben dem Verorten von Strings à la GooglemapsAPI:

yqlgeo.get('cologne, DE',function(o){
  alert(o.place.name+' ('+
  o.place.centroid.latitude+','+
  o.place.centroid.longitude+
')');
})

…auch mal eben Verorten von IPs:

yqlgeo.get('217.12.14.240',function(o){
  alert(o.place.name + ',' + o.place.country.content +
    ' (' + o.place.centroid.latitude + ',' +
    o.place.centroid.longitude + ')'
  );
});

…Usern, URLS und verlorengegangenen Schlüsseln.

Cooles Ding – Lohnt sich definitiv mal anzuschauen!