cpsit/typo3-personio-jobs

TYPO3 CMS Extension to integrate jobs from Personio Recruiting API

0.5.10 2024-03-15 08:37 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0
• ext-json: *
• ext-mbstring: *
• cuyz/valinor: ^1.3
• mtownsend/xml-to-array: ^2.0
• psr/event-dispatcher: ^1.0
• psr/http-message: ^1.0 || ^2.0
• symfony/console: ^5.4 || ^6.0 || ^7.0
• typo3/cms-core: ^11.5 || ^12.4 || ~13.0.0
• typo3/cms-extbase: ^11.5 || ^12.4 || ~13.0.0
• typo3/cms-frontend: ^11.5 || ^12.4 || ~13.0.0

Requires (Dev)

• armin/editorconfig-cli: ^1.5 || ^2.0
• brotkrueml/schema: ^2.7 || ^3.0
• ergebnis/composer-normalize: ^2.29
• helmich/typo3-typoscript-lint: ^3.0
• phpstan/extension-installer: ^1.2
• phpstan/phpstan: ^1.10
• phpstan/phpstan-phpunit: ^1.3
• phpunit/phpcov: ^8.2 || ^9.0 || ^10.0
• saschaegerer/phpstan-typo3: ^1.8
• ssch/typo3-rector: ^1.1
• typo3/coding-standards: ^0.8.0@dev
• typo3/testing-framework: ^7.0.2 || ^8.0.9

Suggests

• brotkrueml/schema: Include JSON schema on job detail pages (^2.7 || ^3.0)

Conflicts

• cuyz/valinor: 1.8.0

GPL-2.0-or-later

• Juliane Wundermann
• Elias Häußler

README

TYPO3 extension personio_jobs

📦 Packagist | 🐥 TYPO3 extension repository | 💾 Repository | 🐛 Issue tracker

An extension for TYPO3 CMS that integrates jobs from Personio Recruiting API into TYPO3. It provides a console command to import jobs into modern-typed value objects. In addition, plugins for list and detail views are provided with preconfigured support for Bootstrap v5 components.

🚀 Features

• Console command to import jobs from Personio Recruiting API
• Usage of modern-typed value objects during the import process
• Plugins for list and detail view
• Optional support for JSON Schema on job detail pages using EXT:schema
• Compatible with TYPO3 11.5 LTS, 12.4 LTS and 13.0

🔥 Installation

Composer

composer require cpsit/typo3-personio-jobs

💡 If you want to use the JSON schema feature, you must additionally require the schema extension:

composer require brotkrueml/schema

TER

Alternatively, you can download the extension via the TYPO3 extension repository (TER).

First-step configuration

Once installed, make sure to include the TypoScript setup at EXT:personio_jobs/Configuration/TypoScript in your root template.

⚡ Usage

Plugins

The extension provides two plugins:

Icon	Description
	Personio: Job list Lists all imported jobs as unordered list. Each list item shows the job title, office and schedule and links to the job's detail view.
	Personio: Job detail Shows a single job, including several job properties and all imported job descriptions. In addition, it renders a button to apply for the job.

Command-line usage

personio-jobs:import

typo3 personio-jobs:import <storage-pid> [options]

The following command parameters are available:

Command parameter	Description	Required	Default
storage-pid	Storage pid of imported jobs	✅	–
-f, --force	Enforce re-import of unchanged jobs	–	no
--no-delete	Do not delete orphaned jobs	–	no
--no-update	Do not update imported jobs that have been changed	–	no
--dry-run	Do not perform database operations, only display changes	–	no

💡 Increase verbosity with --verbose or -v to show all changes, even unchanged jobs that were skipped.

Code usage

The Personio job import process can also be triggered directly within PHP. For this, two services exist:

• PersonioApiService provides the main functionality to fetch jobs from Personio API and return them as hydrated Job models. Note that these jobs are not yet persisted. Instead, they only represent the current Personio job feed as strong-typed value objects.
• PersonioImportService provides additional functionality to actually persist imported jobs. Under the hood, the previously mentioned PersonioApiService is called to fetch jobs, followed by their actual persistence. For the import process, a set of import settings is available:
  • int $storagePid: Page ID where to persist new or updated jobs.
  • bool $updateExistingJobs = true: Define whether to update jobs that were already imported, but have changed in the meantime.
  • bool $deleteOrphans = true: Define whether to delete jobs that are no longer available on Personio.
  • bool $forceImport = false: Select whether existing, unchanged jobs should be re-imported.
  • bool $dryRun = false: Do not perform any persistence operations, just fetch and validate jobs.

Fetch jobs from Personio API

use CPSIT\Typo3PersonioJobs\Service\PersonioApiService;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$apiService = GeneralUtility::makeInstance(PersonioApiService::class);
$jobs = $apiService->getJobs();

foreach ($jobs as $job) {
    echo 'Successfully fetched job: ' . $job->getName() . PHP_EOL;
}

Import jobs from Personio API

use CPSIT\Typo3PersonioJobs\Service\PersonioImportService;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$importService = GeneralUtility::makeInstance(PersonioImportService::class);
$result = $importService->import();

foreach ($result->getNewJobs() as $newJob) {
    echo 'Imported new job: ' . $newJob->getName() . PHP_EOL;
}

foreach ($result->getUpdatedJobs() as $updatedJob) {
    echo 'Updated job: ' . $updatedJob->getName() . PHP_EOL;
}

foreach ($result->getRemovedJobs() as $removedJob) {
    echo 'Removed job: ' . $removedJob->getName() . PHP_EOL;
}

foreach ($result->getSkippedJobs() as $skippedJob) {
    echo 'Skipped job: ' . $skippedJob->getName() . PHP_EOL;
}

JSON schema

In combination with EXT:schema, a JSON schema for a single job is included on job detail pages. It is rendered as type JobPosting and includes some generic job properties.

⚠️ The schema extension must be installed to use this feature. Read more in the installation section above.

📂 Configuration

TypoScript

The following TypoScript constants are available:

TypoScript constant	Description	Required	Default
plugin.tx_personiojobs.view.templateRootPath	Path to template root	–	–
plugin.tx_personiojobs.view.partialRootPath	Path to template partials	–	–
plugin.tx_personiojobs.view.layoutRootPath	Path to template layouts	–	–

Extension configuration

The following extension configuration options are available:

Configuration key	Description	Required	Default
apiUrl	URL to Personio job page, e.g. https://my-company.jobs.personio.de	✅	–

Routing configuration

On each import, a slug is generated. The slug can be used for an advanced routing configuration of job detail pages.

Example:

# config/sites/<identifier>/config.yaml

routeEnhancers:
  PersonioJobDetail:
    type: Extbase
    limitToPages:
      # Replace with the actual detail page id
      - 10
    extension: PersonioJobs
    plugin: Show
    routes:
      -
        routePath: '/job/{job_title}'
        _controller: 'Job::show'
        _arguments:
          job_title: job
    defaultController: 'Job::show'
    aspects:
      job_title:
        type: PersistedAliasMapper
        tableName: tx_personiojobs_domain_model_job
        routeFieldName: slug

⏰ Events

PSR-14 events can be used to modify jobs and job schemas. The following events are available:

• AfterJobsImportedEvent
• AfterJobsMappedEvent
• EnrichJobPostingSchemaEvent

🚧 Migration

0.4.x → 0.5.x

Decouple import process

Import process is moved to a separate service class.

• All import operations are now performed by the new PersonioImportService class.
• PersonioService was renamed to PersonioApiService. Replace all usages of this class by the new class name.
• Import results are now properly displayed by objects of the new ImportResult class.
• Public methods in AfterJobsImportedEvent have changed to match the new ImportResult class. Use the new public method AfterJobsImportedEvent::getImportResult() instead of previously available methods.

0.3.x → 0.4.x

Finalize SchemaFactory

SchemaFactory is now final and cannot be extended anymore.

• Remove classes extending from SchemaFactory.
• Replace customizations of the SchemaFactory by an event listener for the EnrichJobPostingSchemaEvent PSR-14 event.

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

💎 Credits

The Personio logo as part of all distributed icons is a trademark of Personio SE & Co. KG.

⭐ License

This project is licensed under GNU General Public License 2.0 (or later).