PHPackages                             waaseyaa/northcloud - 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. waaseyaa/northcloud

ActiveLibrary[API Development](/categories/api)

waaseyaa/northcloud
===================

North Cloud client, content sync, and search provider for Waaseyaa applications

v0.1.0-alpha.259(2w ago)02.5k↑271.4%2GPL-2.0-or-laterPHPPHP >=8.5

Since Apr 16Pushed 1w agoCompare

[ Source](https://github.com/waaseyaa/northcloud)[ Packagist](https://packagist.org/packages/waaseyaa/northcloud)[ RSS](/packages/waaseyaa-northcloud/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (36)Versions (118)Used By (2)

waaseyaa/northcloud
===================

[](#waaseyaanorthcloud)

North Cloud client, content sync, and search provider for Waaseyaa applications.

What this package gives you
---------------------------

[](#what-this-package-gives-you)

- **`NorthCloudClient`** — HTTP client for the North Cloud REST API (search, people, band office, dictionary, crawl jobs).
- **`NorthCloudCache`** — SQLite-backed response cache.
- **`NorthCloudSearchProvider`** — Implements `Waaseyaa\Search\SearchProviderInterface` so NC becomes a drop-in search backend.
- **`NcSyncService` + `NcSyncWorker` + `northcloud:sync` command** — Generic content ingestion orchestrator that pulls NC search hits and persists them as Waaseyaa entities.
- **`NcHitToEntityMapperInterface`** — The extension seam. Implement one of these per target entity type in your app; the package handles everything else.

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

[](#installation)

```
composer require waaseyaa/northcloud
```

Publish the config (optional):

```
./bin/waaseyaa config:publish northcloud
```

Set env vars:

```
NORTHCLOUD_BASE_URL=https://api.northcloud.one
NORTHCLOUD_API_TOKEN=              # only needed for authenticated endpoints
```

Usage: hooking up content sync in your app
------------------------------------------

[](#usage-hooking-up-content-sync-in-your-app)

Implement one mapper per entity type you want to populate from North Cloud:

```
use Waaseyaa\NorthCloud\Sync\NcHitToEntityMapperInterface;

final class NcHitToKnowledgeItemMapper implements NcHitToEntityMapperInterface
{
    public function entityType(): string
    {
        return 'knowledge_item';
    }

    public function dedupField(): string
    {
        return 'source_url';
    }

    public function supports(array $hit): bool
    {
        $topics = $hit['topics'] ?? [];
        return is_array($topics) && in_array('indigenous', $topics, true);
    }

    public function map(array $hit): array
    {
        return [
            'title' => (string) ($hit['title'] ?? ''),
            // External HTML must be sanitized here against the destination
            // field's allowlist before it is persisted.
            'body' => $this->htmlSanitizer->sanitize(
                (string) ($hit['snippet'] ?? $hit['body'] ?? ''),
            ),
            'source_url' => (string) ($hit['url'] ?? ''),
            // ...app-specific fields
        ];
    }
}
```

`NcHitToEntityMapperInterface::map()` is the trust boundary for North Cloud content. The sync service cannot safely apply one generic sanitizer because each destination field owns a different markup contract. Mapper implementations must sanitize external HTML before returning rendered or rich-text field values; plain text and identifiers should be validated/coerced for their destination types.

Register the mapper in your `AppServiceProvider`:

```
$mapperRegistry = $container->get(MapperRegistry::class);
$mapperRegistry->register(new NcHitToKnowledgeItemMapper(/* deps */));
```

Run a sync:

```
./bin/waaseyaa northcloud:sync --limit=20
./bin/waaseyaa northcloud:sync --dry-run
./bin/waaseyaa northcloud:sync --since=2026-01-01
```

Architecture
------------

[](#architecture)

```
  NC API
    ↓
NorthCloudClient  ──►  NorthCloudCache (SQLite)
    ↓
NcSyncService  ──►  MapperRegistry  ──►  your NcHitToEntityMapperInterface
    ↓
EntityTypeManager  ──►  persisted entities

```

One NC hit may produce multiple entities — every registered mapper whose `supports()` returns true gets to create one.

Status
------

[](#status)

v0.1.0-alpha — API surface not yet stable. See [waaseyaa/framework#TBD](https://github.com/waaseyaa/framework/issues) for rollout plan.

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance97

Actively maintained with recent releases

Popularity23

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 71.4% 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 ~1 days

Total

117

Last Release

14d ago

PHP version history (2 changes)v0.1.0-alpha.143PHP >=8.4

v0.1.0-alpha.176PHP >=8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/25d0ff572e93e3461e5180a920725d65691fd1e15e2d914b254dbbc2d6c393bd?d=identicon)[jonesrussell](/maintainers/jonesrussell)

---

Top Contributors

[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (85 commits)")[![jonesrussell](https://avatars.githubusercontent.com/u/499552?v=4)](https://github.com/jonesrussell "jonesrussell (34 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/waaseyaa-northcloud/health.svg)

```
[![Health](https://phpackages.com/badges/waaseyaa-northcloud/health.svg)](https://phpackages.com/packages/waaseyaa-northcloud)
```

PHPackages © 2026

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