Add KiCad HTTP Library API v2 with volatile field support#1260
Open
Sebbeben wants to merge 27 commits intoPart-DB:masterfrom
Open
Add KiCad HTTP Library API v2 with volatile field support#1260Sebbeben wants to merge 27 commits intoPart-DB:masterfrom
Sebbeben wants to merge 27 commits intoPart-DB:masterfrom
Conversation
- Add Stock field showing total available quantity across all part lots - Add Storage Location field when parts have stored locations - Resolve actual datasheet PDF from attachments (by type name, attachment name, or first PDF) instead of always linking to Part-DB page - Keep Part-DB page URL as separate "Part-DB URL" field - Add ETag and Cache-Control headers to all KiCad API endpoints - Support conditional requests (If-None-Match) returning 304 - Categories/part lists cached 5 min, part details cached 1 min
- Add comprehensive KiCadHelperTest with 14 test cases covering: - Stock quantity calculation (zero, single lot, multiple lots) - Stock exclusion of expired and unknown-quantity lots - Storage location display (present, absent, multiple) - Datasheet URL resolution by type name, attachment name, PDF extension - Datasheet fallback to Part-DB URL when no match - "Data sheet" (with space) name variant matching - Fix PDF extension detection for external attachments (getExtension() returns null for external-only attachments, now also parses URL path)
- Use empty Response instead of JsonResponse(null) for 304 Not Modified to avoid sending "null" as response body - Guard parse_url() result with is_string() since it can return false for malformed URLs - Move storage location tracking inside the availability check so expired and unknown-quantity lots don't contribute locations
The test was requesting /parts/1.json instead of /parts/2.json and had Part 1's expected data. Now tests Part 2 which inherits EDA info from its category and footprint, verifying the inheritance behavior.
Replace manual If-None-Match comparison with Response::setEtag() and Response::isNotModified(), which properly handles ETag quoting, weak vs strong comparison, and 304 response cleanup. Fixes PHPStan return type error and CI test failures.
Add a kicad_export checkbox to parameters, allowing users to control which specifications appear as fields in the KiCad HTTP library API. Parameters with kicad_export enabled are included using their formatted value, without overwriting hardcoded fields like description or Stock.
Console command that populates KiCad footprint/symbol paths on Footprint and Category entities based on name-to-library mappings. Supports dry-run, force overwrite, and list modes. Includes 130+ footprint mappings and 30+ category symbol mappings for KiCad 9.x standard libraries.
Add user-friendly column aliases (kicad_symbol, kicad_footprint, kicad_reference, kicad_value, eda_exclude_bom, etc.) to the CSV import system. Users can now bulk-set KiCad symbols, footprints, and other EDA metadata via CSV/Excel import without knowing the internal dot notation.
Users can now select multiple parts in any parts table and batch-edit their EDA/KiCad fields (symbol, footprint, reference prefix, value, visibility, exclude from BOM/board/sim). Each field has an "Apply" checkbox so users control exactly which fields are changed.
Add @var type annotations for Doctrine repository findAll() calls so PHPStan can resolve getEdaInfo() on Footprint/Category entities. Fix array return type for numeric-string keys and add explicit callback to array_filter to satisfy strict rules.
- Add required=false to TriStateCheckboxType fields so HTML5 validation doesn't force users to check visibility/BOM/board checkboxes - Pre-populate form fields when all selected parts share the same EDA value, so users can see current state before editing
…OM improvements - Add KiCad API v2 endpoints (/kicad-api/v2) with volatile field support for stock and storage location (shown but not saved to schematic) - Add kicad_export flag to Orderdetail entity for per-supplier SPN control (backward compatible: if no flag set, all SPNs exported as before) - Add EDA completeness indicator column in parts datatable (bolt icon) - Add ?minimal=true query param for faster category parts loading - Improve category descriptions (use comment instead of URL when available) - Improve BOM importer multi-footprint support: merge entries by Part-DB part ID when linked, tracking footprint variants in comments - Fix KiCost manf/manf# fields always present (not conditional on orderdetails) - Fix duplicate getEdaInfo() call in shouldPartBeVisible - Consolidate supplier SPN and KiCost field generation into single loop
Add options default to ORM column definition so schema:update works correctly on SQLite test databases.
New setting "Datasheet field links to PDF" in KiCad EDA settings. When enabled (default), the datasheet field resolves to the actual PDF attachment URL. When disabled, it links to the Part-DB page (old behavior). Configurable via settings UI or EDA_KICAD_DATASHEET_AS_PDF env var.
The settings bundle stores values in the database. When upgrading from a version without datasheetAsPdf, the stored JSON lacks this key, causing a TypeError when assigning null to a non-nullable bool. Making it nullable with a fallback in KiCadHelper fixes the upgrade path.
- KiCadApiV2ControllerTest: root, categories, parts, volatile fields, v1 vs v2 comparison, cache headers, 304 conditional request, auth - BatchEdaControllerTest: page load, empty redirect, form submission
Add tests for: applying all EDA fields at once, custom redirect URL, and verifying unchecked fields are skipped.
…rsioning Changes based on jbtronics' review of PR Part-DB#1241: - Rename kicad_export -> eda_visibility (entities, forms, templates, translations, tests) with nullable bool for system default support - Merge two database migrations into one (Version20260211000000) - Rename createCachedJsonResponse -> createCacheableJsonResponse - Change bool $apiV2 -> int $apiVersion with version validation - EDA visibility field only shown for part parameters, not other entities - PopulateKicadCommand: check alternative names of footprints/categories - PopulateKicadCommand: support external JSON mapping file (--mapping-file) - Ship default mappings JSON at contrib/kicad-populate/default_mappings.json - Add system-wide defaultEdaVisibility setting in KiCadEDASettings - Add KiCad HTTP Library v2 spec link in controller docs
…late command docs Add 5 new tests for PopulateKicadCommand covering: - Custom mapping file overriding defaults - Invalid JSON mapping file error handling - Missing mapping file error handling - Footprint alternative name matching - Category alternative name matching Update contrib README to document --mapping-file option, alternative name matching, and custom JSON mapping format.
Remove v2 controller, tests, and volatile field support from this PR. The v2 API will be submitted as a separate PR for focused discussion.
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## master #1260 +/- ##
============================================
+ Coverage 54.77% 55.97% +1.19%
- Complexity 8012 8175 +163
============================================
Files 601 605 +4
Lines 25690 26388 +698
============================================
+ Hits 14072 14770 +698
Misses 11618 11618 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
5 tasks
KiCadHelper: Add tests for orderdetail eda_visibility filtering, backward compatibility when no flags set, manufacturer/KiCost fields, and parameter with empty name skipping. PopulateKicadCommand: Add tests for mapping file with both footprints and categories sections, and mapping file with only categories.
Implements preliminary support for the KiCad HTTP Library API v2 spec (currently in draft). Key differences from v1: - Volatile fields: Stock and Storage Location are marked volatile (shown in KiCad UI but not saved to schematic files) - Root endpoint returns links to categories endpoint - Uses int $apiVersion parameter for clean version switching v2 spec draft: https://gitlab.com/RosyDev/kicad-dev-docs/-/blob/http-lib-v2/content/apis-and-binding/http-libraries/http-lib-v2-00.adoc
Sebbeben
force-pushed
the
feature/kicad-api-v2
branch
from
c1cb018 to
4427ba8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements preliminary support for the KiCad HTTP Library API v2 spec (currently in draft). Split out from #1241 as requested by @jbtronics for focused discussion.
Key differences from v1:
volatile(shown in KiCad UI but not saved to schematic files)int $apiVersionfor clean version switching inKiCadHelperAPI spec references:
Changes
src/Controller/KiCadApiV2Controller.php- New v2 controller at/kicad-api/v2/src/Services/EDA/KiCadHelper.php- Addedint $apiVersionparameter with volatile field supporttests/Controller/KiCadApiV2ControllerTest.php- Full test coverage for v2 endpointsTest plan
"volatile": "True"on Stock and Storage Location fields/kicad-api/v2/) returns links to categories endpoint