PHPackages                             nordkirche/nkc-base - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. nordkirche/nkc-base

ActiveTypo3-cms-extension[API Development](/categories/api)

nordkirche/nkc-base
===================

Nordkirche NAPI Client Base Library

12.4.2(1y ago)181922GPL-2.0PHP

Since May 31Pushed 1y ago1 watchersCompare

[ Source](https://github.com/Nordkirche/nkc-base)[ Packagist](https://packagist.org/packages/nordkirche/nkc-base)[ RSS](/packages/nordkirche-nkc-base/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (3)Versions (17)Used By (2)

TYPO3 Extension nkc\_base
=========================

[](#typo3-extension-nkc_base)

Die Extension stellt einige grundlegende Funktionen für die Nordkirche API konsumierenden Extensions (nkc\_address, nkc\_event) zur Verfügung. Dazu gehören

- einen ApiService für das NDK
- einen Base-Controller für die NAPI Extensions
- ein TCA- bzw. Flexform-Feld für das TYPO3 Backend, um auf NAPI Elemente zuzugreifen
- einen Scheduler Job für die Synchronisierung der Kategorien mit der NAPI
- einen Scheduler Job für den Warm-Up des Karten-Marker Caches
- diverse ViewHelper für die Ausgabe und das Handling von NAPI Inhalten

Voraussetzungen
---------------

[](#voraussetzungen)

Diese Extension benötigt

```
nordkirche/NDK ^2.0
TYPO3 12.4

```

Installation
------------

[](#installation)

Die Installation der Extension erfolgt über composer, da bei dieser Installation auch alle Abhängigkeiten mit installiert werden müssen.

```
composer req nordkirche/nkc-base

```

Konfigurieren Sie anschließend den NAPI Zugang im Bereich der Extension Konfiguration. Sie erhalten Ihren NAPI Zugang beim AfÖ der Nordkirche.

Alternativ können Sie in der AdditionalConfiguration.php die Konfiguration hinterlegen.

```
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nkc_base'] = [
    'NDK_NAPI_PROTOCOL' => 'https',
    'NDK_NAPI_HOST' => 'www.nordkirche.de',
    'NDK_NAPI_PATH' => 'api/',
    'NDK_NAPI_PORT' => '443',
    'NDK_NAPI_VERSION' => '1',
    'NDK_NAPI_USER_ID' => '*******',
    'NDK_NAPI_ACCESS_TOKEN' => '*******',
    'NDK_NAPI_TIMEOUT' => 30
];

```

ApiService
----------

[](#apiservice)

Der APIService stellt ausschließlich statische Methoden bereit, um die Initialisierung und Nutzung des NDK zu vereinfachen

### Die Methoden

[](#die-methoden)

#### ApiService::get()

[](#apiserviceget)

Der Aufruf erfolgt ohne Parameter. Die Methode liefert eine NDK Instanz zurück. Sollte noch keine Instanz im Service registriert sein, wird eine neue erstellt. Dabei greift der Service auf Zugangsdaten / Konfiguration aus der Extension Configuration (ext\_conf\_template.txt) zurück.

#### ApiService::getRepository($object)

[](#apiservicegetrepositoryobject)

Beim Aufruf wird ein NAPI Objektname erwartet (event, person, institution, ...). Die Methode liefert das Repository für das Objekt zurück, mit dessen Hilfe dann ein Request gegen die NAPI vorgenommen werden kann.

#### ApiService::getQuery($object)

[](#apiservicegetqueryobject)

Beim Aufruf wird ein NAPI Objektname erwartet (event, person, institution, ...). Die Methode liefert ein Query für das Objekt zurück, mit dessen Hilfe dann ein Query gebaut werden kann.

#### ApiService::getAllItems($repository, $query, $includes = \[\], $pageSize = 50)

[](#apiservicegetallitemsrepository-query-includes---pagesize--50)

Die NAPI liefert aus Gründen der Performance pro Request maximal 99 Objekte zurück. Weitere Objekte lassen sich nur durch Paginierung abrufen. Diese Methode ein Helper, um wirklich alle Objekte für ein Query abzurufen.

```
$repository - Repository Instanz
$query - Query Instanz
$includes - ein Array mit den Includes (siehe NDK Dokumentation)
$pageSize - die Anzahl Objekte pro Abruf

```

### Code Beispiele

[](#code-beispiele)

#### Eine Repository Instanz über die API Factory holen

[](#eine-repository-instanz-über-die-api-factory-holen)

```
$api = \Nordkirche\NkcBase\ApiService::get();
$eventRepository = $api->factory(\Nordkirche\Ndk\Domain\Repository\EventRepository::class);

```

#### Eine Repository Instanz über den ApiService holen

[](#eine-repository-instanz-über-den-apiservice-holen)

```
$eventRepository = \Nordkirche\NkcBase\ApiService::getRepository('event');

```

#### Ein Veranstaltungs-Query bauen und gegen die NAPI anfragen

[](#ein-veranstaltungs-query-bauen-und-gegen-die-napi-anfragen)

```
$eventRepository = $api->factory(\Nordkirche\Ndk\Domain\Repository\EventRepository::class);
$eventQuery = \Nordkirche\NkcBase\ApiService::getQuery('event');

# Alle Veranstaltungen ab heute
$eventQuery->setTimeFromStart(new \DateTime(date('Y-m-d')));

$events = $eventRepository->get($eventQuery);
$allEvents = \Nordkirche\NkcBase\ApiService\ApiService::getAllItems($eventRepository, $eventQuery);

```

Das Ergebnis ist ein Array von NAPI Objekten

### Fehlerbehandlung

[](#fehlerbehandlung)

Es empfiehlt sich, für Requests gegen die NAPI ein Exception-Handling zu nutzen, damit es nicht zu Ooops Meldungen im Frontend kommt, wenn die NAPI einmal nicht schnell genug reagiert oder einen Fehler zurück gibt. Die Standard-Limitierung für Requests gegen die NAPI liegt bei 20 Sekungen und kann über die Extension-Konfiguration angepasst werden.

```
try {
    # Veranstaltungen holen
    $events = $eventRepository->get($eventQuery);
} catch (\Exception $e) {
    # Fehlerbahandlung
    ...
}

```

Wenn Sie prüfen möchten, welche NAPI Zugriffe von Ihrem System erfolgen, können Sie ein Logfile definieren, in das alle Requests protokolliert werden:

```
    $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nkc_base']['NDK_LOG_FILE'] = '/shared/ndk.log';

```

Die Log Funktion wird nur im Development Context unterstützt.

Base Controller für Extbase Extensions
--------------------------------------

[](#base-controller-für-extbase-extensions)

Der Base-Controller sollte von einer NAPI basierten Extbase Extension beerbt werden:

```
    class myFancyNapiController extends \Nordkirche\NkcBase\BaseController

```

Der Controller bringt eine initializeAction Methode mit, die bei der Implementierung einer eigenen initializeAction Methode aufgerufen werden sollte.

```
class myFancyNapiController extends \Nordkirche\NkcBase\BaseController {

    public function initializeAction()
    {
        parent::initializeAction();
    }
}

```

Die Methode initialisiert

- $this->api
- $this->napiService

Außerdem mergt sie Flexform Einstellungen mit TypoScript Konfigurationen.

Settings, die in

```
plugin.tx_myfancynapi_pi1.settings.flexformDefault {
    foo = bar
}

```

werden mit Flexform Feldern gemergt, welche dem folgenden Namensschema folgen

```

```

Das Ergebnis liegt im Settings Array

```
$this->settings['flexform']

```

TCA Feld zur Auswahl von NAPI Objekten
--------------------------------------

[](#tca-feld-zur-auswahl-von-napi-objekten)

Für das Backend bringt die Extension ein neues FormEngine Feld mit, mit dem sich NAPI Elemente auswählen lassen. Dieses Feld kann im TCA oder in PlugIn Flexforms eingesetzt werden.

### Beispiel

[](#beispiel)

```

        Diese Veranstaltungen darstellen

            user
            napiItemSelector
            event
            0
            99
            10

```

Scheduler Job zur Synchronisierung von Kategorien
-------------------------------------------------

[](#scheduler-job-zur-synchronisierung-von-kategorien)

Die NAPI verwendet Kategorien, die als Sys-Categories in das eigene TYPO3 System übernommen werden können. Diese Extension stellt dafür einen Scheduler Job zur Verfügung, der z.B. einmal täglich ausgeführt werden kann.

Wichtig: Bitte beachten Sie, dass bei der Verwendung des Jobs selbst angelegte Kategorien überschrieben werden.

Scheduler Job für den Map Cache Warmup
--------------------------------------

[](#scheduler-job-für-den-map-cache-warmup)

Wenn Sie Karten mit vielen Markern darstellen möchten, können Sie den Cache für die Marker durch einen Scheduler Job aufwärmen.

Geben Sie in der Task-Konfiguration die betroffenen Content Elemente an (uid), die berücksichtigt werden sollen.

ViewHelper
----------

[](#viewhelper)

Sie finden in den ViewHelpern jeweils ein Code-Beispiel zur Verwendung

Breaking Changes
----------------

[](#breaking-changes)

Das Paginate Widget wurde entfernt, da TYPO3 ab Version 11.5 keine Widgets mehr unterstützt. Die Nkc Extensions liefern nun ein Array "pagination" an das Template, im Ordner Partials liegt ein Beispiel dafür, wie man aus diesem Attay eine Paginerung baut.

Fluid Styled Content Layout
---------------------------

[](#fluid-styled-content-layout)

Diese Extension bringt ein eigenes Default Layout für Fluid Styled Content mit. Die anderen Nordkirche Extensions, die auf nkc\_base basieren, laden Inhalte per AJAX nach und verwendet dafür das TypoScript CONTENT Objekt. Dieses Verfahren sorgt dafür, dass auch bei einer Extbase JSON View ein <div> um den Content gelegt wird. Um das zu vermeiden, gibt es ein leicht angepasstes Layout.

Wir werden dies ggf. in zukünftigen Versionen ändern, so dass kein eigenes Layout mehr notwenig ist.

Fehler gefunden?
----------------

[](#fehler-gefunden)

Bitte melden Sie Fehler via github

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance43

Moderate activity, may be stable

Popularity19

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 57.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~104 days

Total

14

Last Release

451d ago

Major Versions

10.4.3 → 11.52023-07-10

11.5.5 → 12.4.02024-04-12

11.5.6 → 12.4.22025-02-13

### Community

Maintainers

![](https://www.gravatar.com/avatar/cf6b394e5480faa5d0f875024e79798695c8d7feab0a122354b6ff2a38d7977c?d=identicon)[netzleuchten](/maintainers/netzleuchten)

---

Top Contributors

[![derhansen](https://avatars.githubusercontent.com/u/2629896?v=4)](https://github.com/derhansen "derhansen (4 commits)")[![hmccloy](https://avatars.githubusercontent.com/u/1900080?v=4)](https://github.com/hmccloy "hmccloy (3 commits)")

### Embed Badge

![Health badge](/badges/nordkirche-nkc-base/health.svg)

```
[![Health](https://phpackages.com/badges/nordkirche-nkc-base/health.svg)](https://phpackages.com/packages/nordkirche-nkc-base)
```

###  Alternatives

[sinso/app-routes

Easy way to route rest-like URLs to your code

23110.0k1](/packages/sinso-app-routes)[hn/typo3-mcp-server

TYPO3 extension that provides a Model Context Protocol (MCP) server for interacting with TYPO3 pages and records

708.9k](/packages/hn-typo3-mcp-server)[kitodo/presentation

Base plugins, modules, services and API of the Digital Library Framework. It is part of the community-based Kitodo Digitization Suite.

436.1k5](/packages/kitodo-presentation)[friendsoftypo3/interest

REST and CLI API for adding, updating, and deleting records in TYPO3. Tracks relations so records can be inserted in any order. Uses remote ID mapping so you don't have to keep track of what UID a record has gotten after import. Data is inserted using backend APIs as if a real human did it, so you can can inspect the record history and undo actions.

111.3k1](/packages/friendsoftypo3-interest)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)