OC Coding Style

2016-08-29T12:28:27Z

Kratenko: fixed some syntax errors at ends of SQL-Strings

The following rules apply to all developers who contribute source code to the Opencaching.de project. This documentation is incomplete / work in progress.

== General rules ==
All source code files must
* not contain TAB characters,
* use 4-char indenting columns,
* be UTF-8 encoded without byte order marks,
* use only LF as line ends, with the current exception of [[Entwicklung/Codedoku#Email-Templates|email templates]], which have RFC-822 CR/LF line ends.

There are some tools in the [https://github.com/OpencachingDeutschland/oc-server3/tree/master/local/devel local/devel] directory for verifying and fixing these things.

== PHP ==
All contributed or modified code sections must fully comply to the [http://www.php-fig.org/psr/psr-2/ PSR-2] standard (which includes [http://www.php-fig.org/psr/psr-1/ PSR-1]), with these exceptions:

* When referencing identifiers (e.g. class and function names) that are defined in non-PSR-2-compliant source code files, their names need not be PSR-2 compliant.
* When writing standalone scripts like those in the 'local', 'util' and 'util2' directories, they need not to comply to the PSR-1 "Side Effects" rule.

Only <code><?php</code> and <code><?=</code> open tags must be used. <code><?</code> (short open tags) must not be used.

== SQL ==
See also: [[Entwicklung/Codedoku#Datenbank]]

All SQL language elements are written in CAPS, and all user-defined identifiers in `backticks`. Inner joins are coded as JOIN and not as WHERE. All variable values inserted into SQLs '''must''' be escaped, either via placeholders like <code>'&1'</code> or via function <code>sql_escape()</code>.

SQL code inserted into PHP code is enclosed in double quotes and generally formatted like this:

$result = sql(
"SELECT `cache_id`, `wp_oc`
FROM `caches`
JOIN `cache_logs` ON `cache_logs`.`cache_id` = `caches`.`cache_id`
WHERE `caches`.`status` IN ('&1', '&2')",
$status1,
$status2
);

Note that the opening " is on a tab position, while the following lines start one column to the right.

If lines get too long, the parameters are moved to the next line(s) and indented to the next indent column (which is ''three'' chars right of the preceding line's keyword):

$result = sql(
"SELECT
`caches`.`cache_id`,
`caches`.`type` AS `cache_type`,
`cache_logs`.`date` AS `log_date`,
`cache_logs`.`type` AS `log_type`
FROM `caches`
JOIN `cache_logs`
ON `cache_logs`.`cache_id` = `caches`.`cache_id`
AND `cache_logs`.`type` = '&1'
WHERE
`caches`.`status` = '&2'
AND `cache_logs`.`user_id` = '&3'",
$logType,
$cacheStatus,
$userId
);

[[Kategorie:Entwicklung|Coding Style]]
[[Kategorie:English pages]]

Cachestatus

2014-07-31T13:01:02Z

Kratenko: Plural von Status ist Status

[[Datei:Statusänderungen per Log.png|thumb|300px|right|Ändern des Cachestatus]]
Der Status eines Geocaches gibt hauptsächlich an, ob der Cache momentan gesucht/gefunden werden kann, oder ob Probleme vorliegen, die ein Suchen verhindern.

Seit der [http://www.opencaching.de/articles.php?page=changelog#v3.0.8 Opencaching-Version 8] sind Statusänderungen an ein [[Das Onlinelog|Log]] gebunden, wie es auf anderen Plattformen schon länger üblich war. Dadurch verpassen Beobachter zum einen keine einzige Statusänderung mehr, zum anderen ist auch für Nicht-Beobachter klar erkennbar, wann ein Cache suchbar oder nicht suchbar war. Ein Geocache bei Opencaching.de kann folgende Status annehmen, die vom [[Besitzer]] oder einem Mitglied des [[Support|Support-Teams]] gesetzt werden können:

==== Noch nicht veröffentlicht ====
Diesen Status erhält ein neues Opencaching-[[Listing]], wenn du zunächst „[[Erstellen einer Cachebeschreibung/ Listing#Veröffentlichung|Noch nicht veröffentlichen]]“ gewählt hast. Es bleibt für andere Benutzer unsichtbar, bis du es zur Veröffentlichung freigibst.

Damit man keinen Cache versehentlich veröffentlicht, geschieht die Freigabe nicht per Log, sondern man bearbeitet das Cachlisting und ändert zwei Einträge:
* Status = „kann gesucht werden“
* Veröffentlichung = „sofort veröffentlichen“

==== Kann gesucht werden/ Wartungslog ====
[[Datei:Wartungslog 2.png|thumb|300px|right|Wartungslog im Logzähler]]
[[Datei:Wartungslog.png|thumb|300px|left|Wartungslog schreiben]]
Das ist der Normalzustand eines Caches. Die Bedeutung ist klar: Mit dem Geocache ist alles in Ordnung; die Dose kann gefunden werden.

Beim Loggen hat dieser Status noch eine weitere Bedeutung: Er fungiert auch als „Wartungsinfo“ für andere User. Wird im Zustand „Kann gesucht werden“ erneut ein „Kann-gesucht-werden“-Log geschrieben, so signalisiert dies den Suchenden, dass der Cache kontrolliert wurde und dass alles OK ist. Dieser Logtyp kann vom Owner beliebig oft verwendet werden um immer wieder deutlich zu machen, dass der Cache gewartet worden ist und wirklich vorhanden ist.

Das Wartungslog wird ebenfalls benötigt, um ein nicht verfügbares Listing wieder frei zu geben. Es reicht '''nicht''', aus den Statuslog „Nicht verfügbar“ zu entfernen.

Wurde ein Wartungslog geschrieben, erschein dieses in der Logstatistik oben rechts im Listig. Wird ein Listing durch ein „Kann-gesucht-werden“-Log wieder freigegeben, wird dies oben ebenfalls als Wartung aufgeführt.

Das neue Loglabel seht ihr hier:

[[Datei:Wartungslog 3.png|Logtyp Wartung durchgeführt]]

==== Momentan nicht verfügbar/ Deaktivierungslog====
Dieser Zustand wird vom [[Besitzer]] gesetzt, wenn mit dem Cache etwas nicht in Ordnung ist und die Dose nicht gefunden werden kann. Die Gründe dafür können vielfältig sein: die Dose ist verschwunden, das [[Logbuch]] ist nass und muss erst getauscht werden, der Ort des Cacheverstecks kann wegen einer Baustelle momentan nicht betreten werden, usw.
Der Owner ist anschließend dafür verantwortlich, den Geocache wieder suchbar zu machen (z.B. durch Auslegen einer neuen Dose) und den Status durch ein „Kann-gesucht-werden“-Log wieder auf '''kann gesucht werden''' zu setzen. Ist ein Instandsetzen des Caches nicht möglich, sollte der Cache per Archivierungslog '''archiviert''' werden.

Auch dieser Status kann mehrfach geloggt werden. Dies kann Sinn machen, wenn z.B. ein Cache wegen Waldarbeiten nicht verfügbar ist. So kann dann deutlich gemacht werden: ich habe die Lage im Auge, aber die Arbeiten dauern noch an.

Und so sieht dann das fertige Log aus:

[[Datei:Nicht verfügbar Log.png|Logtyp Nicht verfügbar]]

Außerdem erscheint ein rotes Banner mit dem Hinweis „Dieser Geocache ist nicht verfügbar...“ ganz oben im Listing.

==== Archiviert/ Archivierungslog ====
Dieser Status zeigt an, dass der Cache definitiv nicht mehr gefunden werden kann. Archivierte Caches werden standardmäßig nicht auf der [[Cachekarte]] von Opencaching.de angezeigt. Archiviert ein [[Besitzer]] seinen Geocache, ist es wichtig, dass die ausgelegten Dosen (Finaldose und möglicherweise Dosen von [[Stage|Stationen]]) wieder eingesammelt werden. Ansonsten entsteht [[Geomüll]].

Zur Archivierung wird dann das Archivierungslog geschrieben. Es sieht im Listing so aus:

[[Datei:Archivierung.png|Archivierungslog]]

Außerdem erscheint ein rotes Banner mit dem Hinweis „Dieser Geocache ist archiviert....“ ganz oben im Listing.

==== Gesperrt/ Sperrlog ====
Ein '''gesperrter''' Cache entspricht einem '''archivierten''', mit dem Unterschied, dass im Listing keine Logeinträge mehr möglich sind. Außerdem ist der Cache nicht mehr auf der [[Cachekarte|Karte]] anzeigbar und kann nicht per [[API-Clients#OKAPI-Clients|OKAPI]] abgerufen werden.

Das Sperren eines Listings kann z.B. dann sinnvoll sein, wenn es in den [[Das Onlinelog|Onlinelogs]] zu beleidigenden Diskussionen kommt oder der Owner bei einem Lost Place o.ä. ausdrücklich nicht mehr möchte, dass sich noch Sucher an den Ort begeben und vor allem den Cache hinterher noch loggen. Besonders hier sollte der Logeintrag ausführlich ausfallen um die Gründe dessen deutlich zu machen.
Der fertige Logeintrag sieht dann so aus:

[[Datei:Sperrung.png|Sperrungslog]]

Außerdem erscheint ein Schloßsymbol mit dem Hinweis „Dieser Geocache ist gesperrt....“ ganz oben im Listing.
/* Schloßsymbol war: rotes Banner */

==== Gesperrt + Versteckt ====
Das Listing eines gesperrten und versteckten Caches kann nur vom Owner und vom [[Support|Support-Team]] eingesehen werden. Der Cache ist daher auch nicht auf der [[Cachekarte]] sichtbar. Dieser Status kann nur durch das Support-Team gesetzt und wieder zurückgenommen werden.
Der Status wird nur in Ausnahmefällen verwendet, beispielsweise wenn durch das Listing rechtliche Verstöße wie strafrechtlich relevante Texte/Textpassagen oder [[Urheberrecht|Urheberrechtsverstöße]] vorliegen.

[[Kategorie:Opencaching]]
[[Kategorie:Listings und Logs]]

[[pl:Status skrzynki]]

Opencaching-Wiki - Benutzerbeiträge [de]

OC Coding Style

Cachestatus